From 843340d02bff84295e5fadb7c88742162c6d2e18 Mon Sep 17 00:00:00 2001
From: danakj <danakj@chromium.org>
Date: Mon, 11 Sep 2023 16:32:25 -0400
Subject: [PATCH] Clean up docs on friend overloads for numerics

---
 sus/num/__private/float_methods.inc           | 10 +--
 sus/num/__private/signed_integer_methods.inc  | 84 +++++++++++--------
 .../__private/unsigned_integer_methods.inc    | 60 +++++++------
 sus/num/signed_integer.h                      | 20 ++++-
 sus/num/unsigned_integer.h                    | 32 +++++--
 5 files changed, 126 insertions(+), 80 deletions(-)

diff --git a/sus/num/__private/float_methods.inc b/sus/num/__private/float_methods.inc
index ac4ccf9e0..721210199 100644
--- a/sus/num/__private/float_methods.inc
+++ b/sus/num/__private/float_methods.inc
@@ -317,7 +317,7 @@ sus_pure constexpr inline _self operator-() const {
   return _self(-primitive_value);
 }
 
-/// Satisfies the [`Add<@doc.self>`]($sus::num::Add) concept.
+/// Satisfies the [`Add`]($sus::num::Add) concept for floating point values.
 /// #[doc.overloads=float.+]
 [[nodiscard]] sus_pure friend constexpr inline _self operator+(
     _self l, _self r) noexcept {
@@ -345,7 +345,7 @@ friend constexpr inline _self operator+(_self l, U r) noexcept = delete;
 template <PrimitiveFloat U>
   requires(!std::convertible_to<U, _self>)
 friend constexpr inline _self operator+(U l, _self r) noexcept = delete;
-/// Satisfies the [`Sub<@doc.self>`]($sus::num::Sub) concept.
+/// Satisfies the [`Sub`]($sus::num::Sub) concept for floating point values.
 /// #[doc.overloads=float.-]
 [[nodiscard]] sus_pure friend constexpr inline _self operator-(
     _self l, _self r) noexcept {
@@ -373,7 +373,7 @@ friend constexpr inline _self operator-(_self l, U r) noexcept = delete;
 template <PrimitiveFloat U>
   requires(!std::convertible_to<U, _self>)
 friend constexpr inline _self operator-(U l, _self r) noexcept = delete;
-/// Satisfies the [`Mul<@doc.self>`]($sus::num::Mul) concept.
+/// Satisfies the [`Mul`]($sus::num::Mul) concept for floating point values.
 /// #[doc.overloads=float.*]
 [[nodiscard]] sus_pure friend constexpr inline _self operator*(
     _self l, _self r) noexcept {
@@ -401,7 +401,7 @@ friend constexpr inline _self operator*(_self l, U r) noexcept = delete;
 template <PrimitiveFloat U>
   requires(!std::convertible_to<U, _self>)
 friend constexpr inline _self operator*(U l, _self r) noexcept = delete;
-/// Satisfies the [`Div<@doc.self>`]($sus::num::Div) concept.
+/// Satisfies the [`Div`]($sus::num::Div) concept for floating point values.
 /// #[doc.overloads=float./]
 [[nodiscard]] sus_pure friend constexpr inline _self operator/(
     _self l, _self r) noexcept {
@@ -429,7 +429,7 @@ friend constexpr inline _self operator/(_self l, U r) noexcept = delete;
 template <PrimitiveFloat U>
   requires(!std::convertible_to<U, _self>)
 friend constexpr inline _self operator/(U l, _self r) noexcept = delete;
-/// Satisfies the [`Rem<@doc.self>`]($sus::num::Rem) concept.
+/// Satisfies the [`Rem`]($sus::num::Rem) concept for floating point values.
 ///
 /// The remainder from the division of two floats.
 ///
diff --git a/sus/num/__private/signed_integer_methods.inc b/sus/num/__private/signed_integer_methods.inc
index 9ed216d3e..6295e3b8a 100644
--- a/sus/num/__private/signed_integer_methods.inc
+++ b/sus/num/__private/signed_integer_methods.inc
@@ -561,11 +561,12 @@ sus_pure constexpr inline _self operator~() const& noexcept {
       __private::unchecked_not(__private::into_unsigned(primitive_value)));
 }
 
-/// Satisfies the [`Add<@doc.self>`]($sus::num::Add) concept.
+/// Satisfies the [`Add`]($sus::num::Add) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint.+]
 [[nodiscard]] sus_pure_const friend constexpr inline _self operator+(
@@ -600,11 +601,12 @@ template <class U>
   requires((PrimitiveInteger<U> || PrimitiveEnum<U>) &&
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator+(U l, _self r) noexcept = delete;
-/// Satisfies the [`Sub<@doc.self>`]($sus::num::Sub) concept.
+/// Satisfies the [`Sub`]($sus::num::Sub) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint.-]
 [[nodiscard]] sus_pure friend constexpr inline _self operator-(
@@ -639,11 +641,12 @@ template <class U>
   requires((PrimitiveInteger<U> || PrimitiveEnum<U>) &&
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator-(U l, _self r) noexcept = delete;
-/// Satisfies the [`Mul<@doc.self>`]($sus::num::Mul) concept.
+/// Satisfies the [`Mul`]($sus::num::Mul) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint.*]
 [[nodiscard]] sus_pure friend constexpr inline _self operator*(
@@ -678,11 +681,12 @@ template <class U>
   requires((PrimitiveInteger<U> || PrimitiveEnum<U>) &&
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator*(U l, _self r) noexcept = delete;
-/// Satisfies the [`Div<@doc.self>`]($sus::num::Div) concept.
+/// Satisfies the [`Div`]($sus::num::Div) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint./]
 [[nodiscard]] sus_pure friend constexpr inline _self operator/(
@@ -717,11 +721,12 @@ template <class U>
   requires((PrimitiveInteger<U> || PrimitiveEnum<U>) &&
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator/(U l, _self r) noexcept = delete;
-/// Satisfies the [`Rem<@doc.self>`]($sus::num::Rem) concept.
+/// Satisfies the [`Rem`]($sus::num::Rem) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint.%]
 [[nodiscard]] sus_pure friend constexpr inline _self operator%(
@@ -757,11 +762,12 @@ template <class U>
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator%(U l, _self r) noexcept = delete;
 
-/// Satisfies the [`BitAnd<@doc.self>`]($sus::num::BitAnd) concept.
+/// Satisfies the [`BitAnd`]($sus::num::BitAnd) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint.&]
 [[nodiscard]] sus_pure friend constexpr inline _self operator&(
@@ -792,11 +798,12 @@ template <class U>
   requires((PrimitiveInteger<U> || PrimitiveEnum<U>) &&
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator&(U l, _self r) noexcept = delete;
-/// Satisfies the [`BitOr<@doc.self>`]($sus::num::BitOr) concept.
+/// Satisfies the [`BitOr`]($sus::num::BitOr) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint.|]
 [[nodiscard]] sus_pure friend constexpr inline _self operator|(
@@ -827,11 +834,12 @@ template <class U>
   requires((PrimitiveInteger<U> || PrimitiveEnum<U>) &&
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator|(U l, _self r) noexcept = delete;
-/// Satisfies the [`BitXor<@doc.self>`]($sus::num::BitXor) concept.
+/// Satisfies the [`BitXor`]($sus::num::BitXor) concept for signed integers.
 ///
-/// This operation supports working with primitive signed or unsigned integers
-/// that convert to `@doc.self`, as well as enums. However enum class is
-/// excluded as they require an explicit conversion to a `@doc.self`.
+/// This operation supports shifting with primitive signed or unsigned integers
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=signedint.^]
 [[nodiscard]] sus_pure friend constexpr inline _self operator^(
@@ -862,12 +870,14 @@ template <class U>
   requires((PrimitiveInteger<U> || PrimitiveEnum<U>) &&
            !std::convertible_to<U, _self>)
 friend constexpr inline _self operator^(U l, _self r) noexcept = delete;
-/// Satisfies the [`Shl<@doc.self>`]($sus::num::Shl) concept.
+/// Satisfies the [`Shl`]($sus::num::Shl) concept for signed integers.
 ///
 /// This operation supports shifting with primitive signed or unsigned integers
-/// that convert to `u32`, as well as enums. However enum class is excluded
-/// as they require an explicit conversion to a `u32`. Thus the bound is
-/// `std::convertible_to` (implicit conversion) instead of
+/// that convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
+///
+/// Thus the bound is `std::convertible_to` (implicit conversion) instead of
 /// `sus::construct::From` (explicit conversion).
 ///
 /// #[doc.overloads=signedint.<<]
@@ -884,7 +894,7 @@ template <class U>
   requires(!std::convertible_to<U, u32>)
 [[nodiscard]] sus_pure friend constexpr inline _self operator<<(
     _self l, U r) noexcept = delete;
-/// Satisfies the [`Shr<@doc.self>`]($sus::num::Shr) concept.
+/// Satisfies the [`Shr`]($sus::num::Shr) concept for signed integers.
 ///
 /// #[doc.overloads=signedint.>>]
 [[nodiscard]] sus_pure friend constexpr inline _self operator>>(
diff --git a/sus/num/__private/unsigned_integer_methods.inc b/sus/num/__private/unsigned_integer_methods.inc
index 0f262141f..07ad268c7 100644
--- a/sus/num/__private/unsigned_integer_methods.inc
+++ b/sus/num/__private/unsigned_integer_methods.inc
@@ -594,11 +594,12 @@ sus_pure constexpr inline _self operator~() const& noexcept {
   return _self(__private::unchecked_not(primitive_value));
 }
 
-/// Satisfies the [`Add<@doc.self>`]($sus::num::Add) concept.
+/// Satisfies the [`Add`]($sus::num::Add) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint.+]
 [[nodiscard]] sus_pure friend constexpr inline _self operator+(
@@ -639,11 +640,12 @@ template <class U>
            !((UnsignedPrimitiveInteger<U> || UnsignedPrimitiveEnum<U>) &&  //
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator+(U l, _self r) noexcept = delete;
-/// Satisfies the [`Sub<@doc.self>`]($sus::num::Sub) concept.
+/// Satisfies the [`Sub`]($sus::num::Sub) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint.-]
 [[nodiscard]] sus_pure friend constexpr inline _self operator-(
@@ -684,11 +686,12 @@ template <class U>
            !((UnsignedPrimitiveInteger<U> || UnsignedPrimitiveEnum<U>) &&  //
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator-(U l, _self r) noexcept = delete;
-/// Satisfies the [`Mul<@doc.self>`]($sus::num::Mul) concept.
+/// Satisfies the [`Mul`]($sus::num::Mul) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint.*]
 [[nodiscard]] sus_pure friend constexpr inline _self operator*(
@@ -729,11 +732,12 @@ template <class U>
            !((UnsignedPrimitiveInteger<U> || UnsignedPrimitiveEnum<U>) &&  //
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator*(U l, _self r) noexcept = delete;
-/// Satisfies the [`Div<@doc.self>`]($sus::num::Div) concept.
+/// Satisfies the [`Div`]($sus::num::Div) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint./]
 [[nodiscard]] sus_pure friend constexpr inline _self operator/(
@@ -772,11 +776,12 @@ template <class U>
            !((UnsignedPrimitiveInteger<U> || UnsignedPrimitiveEnum<U>) &&  //
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator/(U l, _self r) noexcept = delete;
-/// Satisfies the [`Rem<@doc.self>`]($sus::num::Rem) concept.
+/// Satisfies the [`Rem`]($sus::num::Rem) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint.%]
 [[nodiscard]] sus_pure friend constexpr inline _self operator%(
@@ -816,11 +821,12 @@ template <class U>
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator%(U l, _self r) noexcept = delete;
 
-/// Satisfies the [`BitAnd<@doc.self>`]($sus::num::BitAnd) concept.
+/// Satisfies the [`BitAnd`]($sus::num::BitAnd) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint.&]
 [[nodiscard]] sus_pure friend constexpr inline _self operator&(
@@ -857,11 +863,12 @@ template <class U>
            !((UnsignedPrimitiveInteger<U> || UnsignedPrimitiveEnum<U>) &&  //
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator&(U l, _self r) noexcept = delete;
-/// Satisfies the [`BitOr<@doc.self>`]($sus::num::BitOr) concept.
+/// Satisfies the [`BitOr`]($sus::num::BitOr) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint.|]
 [[nodiscard]] sus_pure friend constexpr inline _self operator|(
@@ -898,11 +905,12 @@ template <class U>
            !((UnsignedPrimitiveInteger<U> || UnsignedPrimitiveEnum<U>) &&  //
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator|(U l, _self r) noexcept = delete;
-/// Satisfies the [`BitXor<@doc.self>`]($sus::num::BitXor) concept.
+/// Satisfies the [`BitXor`]($sus::num::BitXor) concept for unsigned integers.
 ///
 /// This operation supports working with primitive unsigned integers that
-/// convert to @doc.self, as well as enums. However enum class is excluded as
-/// they require an explicit conversion to a @doc.self.
+/// convert to the safe numeric, as well as enums.
+/// However enum class is excluded as they require an explicit conversion to an
+/// integer.
 ///
 /// #[doc.overloads=unsignedint.^]
 [[nodiscard]] sus_pure friend constexpr inline _self operator^(
@@ -939,7 +947,7 @@ template <class U>
            !((UnsignedPrimitiveInteger<U> || UnsignedPrimitiveEnum<U>) &&  //
              ::sus::mem::size_of<U>() <= ::sus::mem::size_of<_primitive>()))
 friend constexpr inline _self operator^(U l, _self r) noexcept = delete;
-/// Satisfies the [`Shl<@doc.self>`]($sus::num::Shl) concept.
+/// Satisfies the [`Shl`]($sus::num::Shl) concept for unsigned integers.
 ///
 /// #[doc.overloads=unsignedint.<<]
 [[nodiscard]] sus_pure friend constexpr inline _self operator<<(
@@ -954,7 +962,7 @@ template <class U>
   requires(!std::convertible_to<U, u32>)
 [[nodiscard]] sus_pure friend constexpr inline _self operator<<(
     _self l, U r) noexcept = delete;
-/// Satisfies the [`Shr<@doc.self>`]($sus::num::Shr) concept.
+/// Satisfies the [`Shr`]($sus::num::Shr) concept for unsigned integers.
 ///
 /// #[doc.overloads=unsignedint.>>]
 [[nodiscard]] sus_pure friend constexpr inline _self operator>>(
diff --git a/sus/num/signed_integer.h b/sus/num/signed_integer.h
index 001bc153f..f059c19fa 100644
--- a/sus/num/signed_integer.h
+++ b/sus/num/signed_integer.h
@@ -126,7 +126,8 @@ struct [[sus_trivial_abi]] isize final {
 #define _primitive ::sus::num::__private::addr_type<>::signed_type
 #include "sus/num/__private/signed_integer_consts.inc"
 
-/// sus::num::Add<T*, isize> trait.
+/// Satisfies the [`Add`]($sus::num::Add) concept for pointers
+/// (`T*`) with [`isize`]($sus::num::isize).
 ///
 /// Adds a [`isize`]($sus::num::isize) to a pointer, returning the resulting
 /// pointer.
@@ -138,7 +139,8 @@ sus_pure_const constexpr inline T* operator+(T* t, S offset) {
   return t + ptrdiff_t{offset};
 }
 
-/// sus::num::AddAssign<T*, isize> trait.
+/// Satisfies the [`AddAssign`]($sus::num::AddAssign) concept for pointers
+/// (`T*`) with [`isize`]($sus::num::isize).
 ///
 /// Adds a [`isize`]($sus::num::isize) to a referenced pointer, and returns
 /// the input reference.
@@ -150,7 +152,8 @@ constexpr inline T*& operator+=(T*& t, isize offset) {
   return t;
 }
 
-/// sus::num::Sub<T*, isize> trait.
+/// Satisfies the [`Sub`]($sus::num::Sub) concept for pointers
+/// (`T*`) with [`isize`]($sus::num::isize).
 ///
 /// Subtracts a [`isize`]($sus::num::isize) from a pointer, returning the
 /// resulting pointer.
@@ -161,7 +164,8 @@ sus_pure_const constexpr inline T* operator-(T* t, isize offset) {
   return t - ptrdiff_t{offset};
 }
 
-/// sus::num::SubAssign<T*, isize> trait.
+/// Satisfies the [`SubAssign`]($sus::num::SubAssign) concept for pointers
+/// (`T*`) with [`isize`]($sus::num::isize).
 ///
 /// Subtracts a [`isize`]($sus::num::isize) from a referenced pointer, and
 /// returns the input reference.
@@ -173,6 +177,9 @@ constexpr inline T*& operator-=(T*& t, isize offset) {
   return t;
 }
 
+/// Satisfies the [`Shl`]($sus::num::Shl) concept for signed primitive integers
+/// shifted by [`u32`]($sus::num::u32).
+/// #[doc.overloads=signed.prim.<<u32]
 template <class P, Integer U>
   requires((SignedPrimitiveInteger<P> || SignedPrimitiveEnum<P>) &&
            std::convertible_to<U, u32>)
@@ -181,11 +188,15 @@ template <class P, Integer U>
   // return type?
   return l << u32(r).primitive_value;
 }
+/// #[doc.overloads=signed.prim.<<u32]
 template <class P, Integer U>
   requires((SignedPrimitiveInteger<P> || SignedPrimitiveEnum<P>) &&
            !std::convertible_to<U, u32>)
 constexpr inline P operator<<(P l, U r) noexcept = delete;
 
+/// Satisfies the [`Shr`]($sus::num::Shr) concept for signed primitive integers
+/// shifted by [`u32`]($sus::num::u32).
+/// #[doc.overloads=signed.prim.>>u32]
 template <class P, Integer U>
   requires((SignedPrimitiveInteger<P> || SignedPrimitiveEnum<P>) &&
            std::convertible_to<U, u32>)
@@ -194,6 +205,7 @@ template <class P, Integer U>
   // return type?
   return l >> u32(r).primitive_value;
 }
+/// #[doc.overloads=signed.prim.>>u32]
 template <class P, Integer U>
   requires((SignedPrimitiveInteger<P> || SignedPrimitiveEnum<P>) &&
            !std::convertible_to<U, u32>)
diff --git a/sus/num/unsigned_integer.h b/sus/num/unsigned_integer.h
index 603eaf6df..7de4b698a 100644
--- a/sus/num/unsigned_integer.h
+++ b/sus/num/unsigned_integer.h
@@ -175,9 +175,11 @@ struct [[sus_trivial_abi]] uptr final {
 #define _primitive ::sus::num::__private::ptr_type<::sus::mem::size_of<uintptr_t>()>::unsigned_type
 #include "sus/num/__private/unsigned_integer_consts.inc"
 
-/// sus::num::Add<T*, usize> trait.
+/// Satisfies the [`Add`]($sus::num::Add) concept for pointers
+/// (`T*`) with [`usize`]($sus::num::usize).
 ///
-/// Adds a [`usize`]($sus::num::usize) to a pointer, returning the resulting pointer.
+/// Adds a [`usize`]($sus::num::usize) to a pointer, returning the resulting
+/// pointer.
 ///
 /// #[doc.overloads=ptr.add.usize]
 template <class T, Unsigned U>
@@ -186,9 +188,11 @@ sus_pure_const constexpr inline T* operator+(T* t, U offset) {
   return t + size_t{offset};
 }
 
-/// sus::num::AddAssign<T*, usize> trait.
+/// Satisfies the [`AddAssign`]($sus::num::AddAssign) concept for pointers
+/// (`T*`) with [`usize`]($sus::num::usize).
 ///
-/// Adds a [`usize`]($sus::num::usize) to a referenced pointer, and returns the input reference.
+/// Adds a [`usize`]($sus::num::usize) to a referenced pointer, and returns the
+/// input reference.
 ///
 /// #[doc.overloads=ptr.add.usize]
 template <class T>
@@ -197,9 +201,11 @@ constexpr inline T*& operator+=(T*& t, usize offset) {
   return t;
 }
 
-/// sus::num::Sub<T*, usize> trait.
+/// Satisfies the [`Sub`]($sus::num::Sub) concept for pointers
+/// (`T*`) with [`usize`]($sus::num::usize).
 ///
-/// Subtracts a  from a pointer, returning the resulting pointer.
+/// Subtracts a [`usize`]($sus::num::usize) from a pointer, returning the
+/// resulting pointer.
 ///
 /// #[doc.overloads=ptr.sub.usize]
 template <class T>
@@ -207,9 +213,11 @@ sus_pure_const constexpr inline T* operator-(T* t, usize offset) {
   return t - size_t{offset};
 }
 
-/// sus::num::SubAssign<T*, usize> trait.
+/// Satisfies the [`SubAssign`]($sus::num::SubAssign) concept for pointers
+/// (`T*`) with [`usize`]($sus::num::usize).
 ///
-/// Subtracts a [`usize`]($sus::num::usize) from a referenced pointer, and returns the input
+/// Subtracts a [`usize`]($sus::num::usize) from a referenced pointer, and
+/// returns the input
 /// reference.
 ///
 /// #[doc.overloads=ptr.sub.usize]
@@ -219,6 +227,9 @@ constexpr inline T*& operator-=(T*& t, usize offset) {
   return t;
 }
 
+/// Satisfies the [`Shl`]($sus::num::Shl) concept for unsigned primitive
+/// integers shifted by [`u32`]($sus::num::u32).
+/// #[doc.overloads=unsigned.prim.<<u32]
 template <class P, Integer U>
   requires((UnsignedPrimitiveInteger<P> || UnsignedPrimitiveEnum<P>) &&
            std::convertible_to<U, u32>)
@@ -227,11 +238,15 @@ template <class P, Integer U>
   // return type?
   return l << u32(r).primitive_value;
 }
+/// #[doc.overloads=unsigned.prim.<<u32]
 template <class P, Integer U>
   requires((UnsignedPrimitiveInteger<P> || UnsignedPrimitiveEnum<P>) &&
            !std::convertible_to<U, u32>)
 constexpr inline P operator<<(P l, U r) noexcept = delete;
 
+/// Satisfies the [`Shr`]($sus::num::Shr) concept for unsigned primitive
+/// integers shifted by [`u32`]($sus::num::u32).
+/// #[doc.overloads=unsigned.prim.>>u32]
 template <class P, Integer U>
   requires((UnsignedPrimitiveInteger<P> || UnsignedPrimitiveEnum<P>) &&
            std::convertible_to<U, u32>)
@@ -240,6 +255,7 @@ template <class P, Integer U>
   // return type?
   return l >> u32(r).primitive_value;
 }
+/// #[doc.overloads=unsigned.prim.>>u32]
 template <class P, Integer U>
   requires((UnsignedPrimitiveInteger<P> || UnsignedPrimitiveEnum<P>) &&
            !std::convertible_to<U, u32>)