Merge pull request #374 from cppalliance/doc_review

Documentation Review

Author: mborland

doc/modules/ROOT/nav.adoc

@@ -6,7 +6,7 @@
 ** xref:examples.adoc#examples_rollover[Rollover Behavior]
 ** xref:examples.adoc#examples_bit[`<bit>` support]
 ** xref:examples.adoc#examples_numeric[`<numeric>` support (Saturating Arithmetic)]
-** xref:examples.adoc#examples_numeric[`<numeric>` support (Numeric Logarithms)]
+** xref:examples.adoc#examples_numeric_algorithms[`<numeric>` support (Numeric Algorithms)]
 ** xref:examples.adoc#examples_mixed_sign[Mixed Signedness Arithmetic]
 ** xref:examples.adoc#examples_to_string[String Conversion (to_string)]
 ** xref:examples.adoc#examples_boost_math_random[Boost Math and Random Integration]

doc/modules/ROOT/pages/api_reference.adoc

@@ -20,6 +20,9 @@ https://www.boost.org/LICENSE_1_0.txt
 
 | xref:literals.adoc[`boost::int128::literals`]
 | User-defined literals for 128-bit integers
+
+| xref:charconv.adoc[`boost::charconv`]
+| `to_chars` and `from_chars` overloads for 128-bit integers (requires Boost.Charconv)
 |===
 
 [#api_types]
@@ -146,7 +149,7 @@ Listed by analogous STL header.
 |===
 | Function | Description
 
-| `abs`
+| xref:int128_t.adoc#i128_math_operators[`abs`]
 | Absolute value
 |===
 
@@ -359,8 +362,8 @@ Listed by analogous STL header.
 | xref:format.adoc#std_format[`<boost/int128/format.hpp>`]
 | Formatting integration for pass:[C++20] `<format>`
 
-| xref:uint128_t.adoc[`<boost/int128/int128.hpp>`]
-| The `int128_t` and `uint128_t` types
+| `<boost/int128/int128.hpp>`
+| The xref:uint128_t.adoc[`uint128_t`] and xref:int128_t.adoc[`int128_t`] types
 
 | xref:stream.adoc[`<boost/int128/iostream.hpp>`]
 | Iostream overloads for `int128_t` and `uint128_t`

doc/modules/ROOT/pages/config.adoc

@@ -19,7 +19,7 @@ These macros allow customization of library behavior. User-configurable macros s
 
 [#enable_cuda]
 - `BOOST_INT128_ENABLE_CUDA`: Defining this macro allows both types and selected functions to be run on both host and device when compiling with NVCC.
-Allowed functions have `BOOST_IN128_HOST_DEVICE` as part of their function signature in their documentation.
+Allowed functions have `BOOST_INT128_HOST_DEVICE` as part of their function signature in their documentation.
 
 [#no_int128]
 - `BOOST_INT128_NO_BUILTIN_INT128`: The user may define this when they do not want the internal implementations to rely on builtin `pass:[__int128]` or `pass:[unsigned __int128]` types.

doc/modules/ROOT/pages/examples.adoc

@@ -304,7 +304,7 @@ signed_value / 4U = 0
 include::example$math_and_random.cpp[]
 ----
 
-.Expected Output
+.Example Output (values vary per run)
 [listing]
 ----
 === uint128_t ===

doc/modules/ROOT/pages/file_structure.adoc

@@ -16,22 +16,25 @@ The entire library can be consumed via `<boost/int128.hpp>`, or by independently
 | Header | Description
 
 | `<boost/int128.hpp>`
-| The complete library (includes all headers below)
+| Convenience header (includes most headers below; does not include `charconv.hpp`, `fmt_format.hpp`, or `random.hpp`)
 
 | xref:bit.adoc[`<boost/int128/bit.hpp>`]
 | Bit manipulation functions
 
 | xref:charconv.adoc[`<boost/int128/charconv.hpp>`]
-| Character conversion (`to_chars`/`from_chars`)
+| Character conversion (`to_chars`/`from_chars`); requires Boost.Charconv headers
 
 | xref:api_reference.adoc#api_macro_literals[`<boost/int128/climits.hpp>`]
 | C-style limit macros (`BOOST_INT128_INT128_MAX`, etc.)
 
+| xref:config.adoc[`<boost/int128/config.hpp>`]
+| Configuration macros
+
 | xref:cstdlib.adoc[`<boost/int128/cstdlib.hpp>`]
 | Division with quotient and remainder (`div`)
 
 | xref:format.adoc[`<boost/int128/fmt_format.hpp>`]
-| `pass:[{fmt}]` library support
+| `pass:[{fmt}]` library support; requires the `pass:[{fmt}]` library
 
 | xref:format.adoc[`<boost/int128/format.hpp>`]
 | C++20 `std::format` support
@@ -50,4 +53,10 @@ The entire library can be consumed via `<boost/int128.hpp>`, or by independently
 
 | xref:numeric.adoc[`<boost/int128/numeric.hpp>`]
 | Numeric functions (`gcd`, `lcm`, saturating arithmetic)
+
+| `<boost/int128/random.hpp>`
+| Traits for usage with Boost.Random
+
+| xref:string.adoc[`<boost/int128/string.hpp>`]
+| `to_string` overloads
 |===

doc/modules/ROOT/pages/format.adoc

@@ -37,7 +37,7 @@ Examples:
 | `{:*^6d}` | `"**42**"` (centered with asterisks)
 |===
 
-NOTE: When no alignment is specified but a width is given (e.g., `{:6d}`), zero-padding is applied from the left.
+NOTE: When no alignment is specified but a `0` prefix and width are given (e.g., `{:06d}`), zero-padding is applied from the left. Without the `0` prefix (e.g., `{:6d}`), space-padding is applied instead, matching `std::format` behavior.
 
 == Sign
 

doc/modules/ROOT/pages/i128_benchmarks.adoc

@@ -12,7 +12,7 @@ https://www.boost.org/LICENSE_1_0.txt
 
 The benchmarks below represent the time in microseconds it takes to perform 20'000'000 operations between two values of random width (e.g. 2x1 words, 1x2 words, etc.).
 On most platforms we use the builtin `\__int128` as the reference benchmark.
-When this is unavailable (such as on 32-bit architectures) we us `boost::multiprecision::int128_t` (abbreviated as `boost::mp::int128_t`) as it is widely used, and known to be portable.
+When this is unavailable (such as on 32-bit architectures) we use `boost::multiprecision::int128_t` (abbreviated as `boost::mp::int128_t`) as it is widely used, and known to be portable.
 On MSVC platforms we use as reference `std::_Signed128` from the header `<__msvc_int128.hpp>` since this is bundled with their compiler.
 
 [#i128_linux]
@@ -56,7 +56,7 @@ image::i128_graphs/linux/x64_relative_performance.png[x64 Relative Performance,
 image::i128_graphs/linux/ARM64_benchmarks.png[ARM64 Benchmark Results, width=100%]
 ////
 
-image::i128_graphs/linux/ARM64_relative_performance.png[x64 Relative Performance, width=100%]
+image::i128_graphs/linux/ARM64_relative_performance.png[ARM64 Relative Performance, width=100%]
 
 === S390x
 

doc/modules/ROOT/pages/mixed_type_ops.adoc

@@ -110,7 +110,7 @@ BOOST_INT128_HOST_DEVICE constexpr bool operator!=(uint128_t lhs, int128_t rhs);
 BOOST_INT128_HOST_DEVICE constexpr bool operator!=(int128_t lhs, uint128_t rhs);
 ----
 
-If the `int128_t` argument is less than 0 returns `false`.
+If the `int128_t` argument is less than 0 returns `true`.
 Otherwise, returns the same as `static_cast<uint128_t>(lhs) != static_cast<uint128_t>(rhs)`.
 
 === Less Than
@@ -152,7 +152,7 @@ If `lhs` is type `int128_t` returns `false` if `lhs < 0`
 If `rhs` is type `int128_t` returns `true` if `rhs < 0`
 Otherwise, returns the same as `static_cast<uint128_t>(lhs) > static_cast<uint128_t>(rhs)`.
 
-=== Less Than or Equal To
+=== Greater Than or Equal To
 
 [source, c++]
 ----
@@ -167,7 +167,7 @@ Otherwise, returns the same as `static_cast<uint128_t>(lhs) pass:[>=] static_cas
 
 == Arithmetic
 
-If you define xref:config.adoc#sign_compare[`BOOST_INT128_ALLOW_SIGN_CONVERSION`], the operators have the following behavior.
+If you define xref:config.adoc#sign_conversion[`BOOST_INT128_ALLOW_SIGN_CONVERSION`], the operators have the following behavior.
 
 === Addition
 

doc/modules/ROOT/pages/numeric.adoc

@@ -57,8 +57,11 @@ Should the `TargetIntegerType` not be able to represent the value of the `Librar
 namespace boost {
 namespace int128 {
 
-constexpr <typename LibraryIntegerType, typename TargetIntegerType>
-BOOST_INT128_HOST_DEVICE constexpr TargetIntegerType saturate_cast(LibraryIntegerType x) noexcept;
+template <typename TargetType>
+BOOST_INT128_HOST_DEVICE constexpr TargetType saturate_cast(uint128_t value) noexcept;
+
+template <typename TargetType>
+BOOST_INT128_HOST_DEVICE constexpr TargetType saturate_cast(int128_t value) noexcept;
 
 } // namespace int128
 } // namespace boost

doc/modules/ROOT/pages/overview.adoc

@@ -24,8 +24,8 @@ When using pass:[C++20] or newer, the library can be consumed as a module `impor
 GCC and Clang offer `__int128` as a non-standard extension on 64-bit targets, but it lacks `std::numeric_limits` specializations, `<iostream>` support, and is absent entirely on MSVC.
 Multiprecision libraries can fill the gap, but typically at the cost of a larger `sizeof` and additional overhead (e.g., Boost.Multiprecision always has an extra word).
 Boost.Int128 solves this by providing types that are exactly 128-bits on every platform.
-Operation implementations rely on compiler intrinsic where available for native performance, and optimized software implementations elsewhere.
-The types provided by the library also have native support being running on GPU using CUDA, along with many of the functions.
+Operation implementations rely on compiler intrinsics where available for native performance, and optimized software implementations elsewhere.
+The types provided by the library also natively support running on GPUs using CUDA, along with many of the functions.
 
 == Use Cases