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

@@ -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                                                                | &#x26
 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).
 

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
-
+#### <a name="H-util-finally" />Non-member functions
 ```cpp
 template <class F>
 auto finally(F&& f) noexcept;