From 9695da9b38471b4f3b5619763d72afcde5b4ae4d Mon Sep 17 00:00:00 2001 From: Werner Henze <34543625+beinhaerter@users.noreply.github.com> Date: Wed, 6 Sep 2023 01:08:36 +0200 Subject: [PATCH] fix and optimize documentation (#1131) - Add anchor for `finally` in `headers.md` so that the link in `README.md` can work - In `README.md` add code formatting for the character types of the `zstring` and `string_span` types - In `README.md` change code formatting to links for GSL types - Vertical alignment --- README.md | 44 ++++++++++++++++++++++---------------------- docs/headers.md | 3 +-- 2 files changed, 23 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a6e78df3..fe01aada 100644 --- a/README.md +++ b/README.md @@ -26,18 +26,18 @@ Feature | Suppo -------------------------------------------------------------------------|:----------:|------------- [**1. Views**][cg-views] | | [owner](docs/headers.md#user-content-H-pointers-owner) | ☑ | An alias for a raw pointer -[not_null](docs/headers.md#user-content-H-pointers-not_null) | ☑ | Restricts a pointer / smart pointer to hold non-null values +[not_null](docs/headers.md#user-content-H-pointers-not_null) | ☑ | Restricts a pointer/smart pointer to hold non-null values [span](docs/headers.md#user-content-H-span-span) | ☑ | A view over a contiguous sequence of memory. Based on the standardized version of `std::span`, however `gsl::span` enforces bounds checking. span_p | ☐ | Spans a range starting from a pointer to the first place for which the predicate is true -[basic_zstring](docs/headers.md#user-content-H-zstring) | ☑ | A pointer to a C-string (zero-terminated array) with a templated char type -[zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char -[czstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char -[wzstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of wchar_t -[cwzstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const wchar_t -[u16zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char16_t -[cu16zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char16_t -[u32zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of char32_t -[cu32zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of const char32_t +[basic_zstring](docs/headers.md#user-content-H-zstring) | ☑ | A pointer to a C-string (zero-terminated array) with a templated char type +[zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `char` +[czstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `const char` +[wzstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `wchar_t` +[cwzstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `const wchar_t` +[u16zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `char16_t` +[cu16zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `const char16_t` +[u32zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `char32_t` +[cu32zstring](docs/headers.md#user-content-H-zstring) | ☑ | An alias to `basic_zstring` with dynamic extent and a char type of `const char32_t` [**2. Owners**][cg-owners] | | [unique_ptr](docs/headers.md#user-content-H-pointers-unique_ptr) | ☑ | An alias to `std::unique_ptr` [shared_ptr](docs/headers.md#user-content-H-pointers-shared_ptr) | ☑ | An alias to `std::shared_ptr` @@ -50,31 +50,31 @@ dyn_array | & move_owner | ☐ | A helper function that moves one `owner` to the other [byte](docs/headers.md#user-content-H-byte-byte) | ☑ | Either an alias to `std::byte` or a byte type [final_action](docs/headers.md#user-content-H-util-final_action) | ☑ | A RAII style class that invokes a functor on its destruction -[finally](docs/headers.md#user-content-H-util-finally) | ☑ | A helper function instantiating `final_action` +[finally](docs/headers.md#user-content-H-util-finally) | ☑ | A helper function instantiating [final_action](docs/headers.md#user-content-H-util-final_action) [GSL_SUPPRESS](docs/headers.md#user-content-H-assert-gsl_suppress) | ☑ | A macro that takes an argument and turns it into `[[gsl::suppress(x)]]` or `[[gsl::suppress("x")]]` [[implicit]] | ☐ | A "marker" to put on single-argument constructors to explicitly make them non-explicit [index](docs/headers.md#user-content-H-util-index) | ☑ | A type to use for all container and array indexing (currently an alias for `std::ptrdiff_t`) joining_thread | ☐ | A RAII style version of `std::thread` that joins -[narrow](docs/headers.md#user-content-H-narrow-narrow) | ☑ | A checked version of `narrow_cast`; it can throw `narrowing_error` +[narrow](docs/headers.md#user-content-H-narrow-narrow) | ☑ | A checked version of `narrow_cast`; it can throw [narrowing_error](docs/headers.md#user-content-H-narrow-narrowing_error) [narrow_cast](docs/headers.md#user-content-H-util-narrow_cast) | ☑ | A narrowing cast for values and a synonym for `static_cast` -[narrowing_error](docs/headers.md#user-content-H-narrow-narrowing_error) | ☑ | A custom exception type thrown by `narrow()` +[narrowing_error](docs/headers.md#user-content-H-narrow-narrowing_error) | ☑ | A custom exception type thrown by [narrow](docs/headers.md#user-content-H-narrow-narrow) [**5. Concepts**][cg-concepts] | ☐ | ## The following features do not exist in or have been removed from the C++ Core Guidelines: Feature | Supported? | Description -----------------------------------|:----------:|------------- -[strict_not_null](docs/headers.md#user-content-H-pointers-strict_not_null) | ☑ | A stricter version of `not_null` with explicit constructors +[strict_not_null](docs/headers.md#user-content-H-pointers-strict_not_null) | ☑ | A stricter version of [not_null](docs/headers.md#user-content-H-pointers-not_null) with explicit constructors multi_span | ☐ | Deprecated. Multi-dimensional span. strided_span | ☐ | Deprecated. Support for this type has been discontinued. basic_string_span | ☐ | Deprecated. Like `span` but for strings with a templated char type -string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of char -cstring_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of const char -wstring_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of wchar_t -cwstring_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of const wchar_t -u16string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of char16_t -cu16string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of const char16_t -u32string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of char32_t -cu32string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of const char32_t +string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `char` +cstring_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `const char` +wstring_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `wchar_t` +cwstring_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `const wchar_t` +u16string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `char16_t` +cu16string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `const char16_t` +u32string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `char32_t` +cu32string_span | ☐ | Deprecated. An alias to `basic_string_span` with a char type of `const char32_t` This is based on [CppCoreGuidelines semi-specification](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gsl-guidelines-support-library). diff --git a/docs/headers.md b/docs/headers.md index 37d78190..310b4743 100644 --- a/docs/headers.md +++ b/docs/headers.md @@ -806,8 +806,7 @@ void operator=(final_action&&) = delete; Move construction is allowed. Copy construction is deleted. Copy and move assignment are also explicitely deleted. -#### Non-member functions - +#### Non-member functions ```cpp template auto finally(F&& f) noexcept;