Correct signed bit int documentation

Author: Stovent

library/core/src/num/int_macros.rs

@@ -1514,15 +1514,41 @@ macro_rules! int_impl {
 
         /// Calculates `self + rhs + carry` without the ability to overflow.
         ///
-        /// Performs "ternary addition" which takes in an extra bit to add, and may return an
-        /// additional bit of overflow. This allows for chaining together multiple additions
-        /// to create "big integers" which represent larger values.
-        ///
-        #[doc = concat!("This can be thought of as a ", stringify!($BITS), "-bit \"full adder\", in the electronics sense.")]
+        /// Performs "signed ternary addition" which takes in an extra bit to add, and may return an
+        /// additional bit of overflow. This signed function is used only on the highest-ordered data,
+        /// for which the signed overflow result indicates whether the big integer overflowed or not.
         ///
         /// # Examples
         ///
-        /// Basic usage
+        /// Standard signed bit integer implementation
+        ///
+        /// ```rs
+        /// #![feature(bigint_helper_methods)]
+        /// struct I16 {
+        ///     pub low: u8, // Low-order bytes has to be unsigned.
+        ///     /// Most Significant Data has to be of the same signedness as the desired type.
+        ///     /// So u8 to implement U16, i8 to implement I16.
+        ///     pub high: i8,
+        /// }
+        ///
+        /// impl I16 {
+        ///     /// Adds `rhs` to `self` and returns true if signed overflow occurs, false otherwise.
+        ///     pub fn overflowing_add(&mut self, rhs: Self) -> bool {
+        ///         let (low_res, low_carry) = self.low.carrying_add(rhs.low, false);
+        ///
+        ///         // The signed `carrying_add` method is used to detect signed overflow.
+        ///         let (high_res, high_carry) = self.high.carrying_add(rhs.high, low_carry);
+        ///
+        ///         self.low = low_res;
+        ///         self.high = high_res;
+        ///         high_carry
+        ///     }
+        /// }
+        ///
+        /// fn main() {}
+        /// ```
+        ///
+        /// General behavior
         ///
         /// ```
         /// #![feature(bigint_helper_methods)]
@@ -1612,13 +1638,41 @@ macro_rules! int_impl {
 
         /// Calculates `self - rhs - borrow` without the ability to overflow.
         ///
-        /// Performs "ternary subtraction" which takes in an extra bit to subtract, and may return
-        /// an additional bit of overflow. This allows for chaining together multiple subtractions
-        /// to create "big integers" which represent larger values.
+        /// Performs "signed ternary subtraction" which takes in an extra bit to subtract, and may return an
+        /// additional bit of overflow. This signed function is used only on the highest-ordered data,
+        /// for which the signed overflow result indicates whether the big integer overflowed or not.
         ///
         /// # Examples
         ///
-        /// Basic usage
+        /// Standard signed bit integer implementation
+        ///
+        /// ```rs
+        /// #![feature(bigint_helper_methods)]
+        /// struct I16 {
+        ///     pub low: u8, // Low-order bytes has to be unsigned.
+        ///     /// Most Significant Data has to be of the same signedness as the desired type.
+        ///     /// So u8 to implement U16, i8 to implement I16.
+        ///     pub high: i8,
+        /// }
+        ///
+        /// impl I16 {
+        ///     /// Subtracts `rhs` from `self` and returns true if signed overflow occurs, false otherwise.
+        ///     pub fn overflowing_sub(&mut self, rhs: Self) -> bool {
+        ///         let (low_res, low_carry) = self.low.borrowing_sub(rhs.low, false);
+        ///
+        ///         // The signed `borrowing_sub` method is used to detect signed overflow.
+        ///         let (high_res, high_carry) = self.high.borrowing_sub(rhs.high, low_carry);
+        ///
+        ///         self.low = low_res;
+        ///         self.high = high_res;
+        ///         high_carry
+        ///     }
+        /// }
+        ///
+        /// fn main() {}
+        /// ```
+        ///
+        /// General behavior
         ///
         /// ```
         /// #![feature(bigint_helper_methods)]