[stdlib] Propagate IntegerArithmeticType docs

184 undocumented public non-operator APIs remain in core

Swift SVN r22227

stdlib/core/Bit.swift

@@ -104,30 +104,40 @@ extension Bit : IntegerArithmeticType {
     return (Bit(rawValue: v.0)!, v.overflow)
   }
   
+  /// Add `lhs` and `rhs`, returning a result and a `Bool` that is
+  /// true iff the operation caused an arithmetic overflow.
   public static func addWithOverflow(
     lhs: Bit, _ rhs: Bit
   ) -> (Bit, overflow: Bool) {
     return _withOverflow(Int.addWithOverflow(lhs.rawValue, rhs.rawValue))
   }
 
+  /// Subtract `lhs` and `rhs`, returning a result and a `Bool` that is
+  /// true iff the operation caused an arithmetic overflow.
   public static func subtractWithOverflow(
     lhs: Bit, _ rhs: Bit
   ) -> (Bit, overflow: Bool) {
     return _withOverflow(Int.subtractWithOverflow(lhs.rawValue, rhs.rawValue))
   }
 
+  /// Multiply `lhs` and `rhs`, returning a result and a `Bool` that is
+  /// true iff the operation caused an arithmetic overflow.
   public static func multiplyWithOverflow(
     lhs: Bit, _ rhs: Bit
   ) -> (Bit, overflow: Bool) {
     return _withOverflow(Int.multiplyWithOverflow(lhs.rawValue, rhs.rawValue))
   }
 
+  /// Divide `lhs` and `rhs`, returning a result and a `Bool` that is
+  /// true iff the operation caused an arithmetic overflow.
   public static func divideWithOverflow(
     lhs: Bit, _ rhs: Bit
   ) -> (Bit, overflow: Bool) {
     return _withOverflow(Int.divideWithOverflow(lhs.rawValue, rhs.rawValue))
   }
 
+  /// Divide `lhs` and `rhs`, returning the remainder and a `Bool` that is
+  /// true iff the operation caused an arithmetic overflow.
   public static func remainderWithOverflow(
     lhs: Bit, _ rhs: Bit
   ) -> (Bit, overflow: Bool) {

stdlib/core/FixedPoint.swift.gyb

@@ -317,8 +317,13 @@ extension ${Self} : RandomAccessIndexType {
   }
 }
 
+// Operations that return an overflow bit in addition to a partial result,
+// helpful for checking for overflow when you want to handle it.
 extension ${Self} {
 % for Method,op in [('add', 'add'), ('subtract', 'sub'), ('multiply', 'mul')]:
+  /// ${Method.capitalize()} `lhs` and `rhs`, returning a result and a
+  /// `Bool` that is true iff the operation caused an arithmetic
+  /// overflow.
   @transparent public
   static func ${Method}WithOverflow(lhs: ${Self}, _ rhs: ${Self}) -> (${Self}, overflow: Bool) {
     var tmp = Builtin.${sign}${op}_with_overflow_${BuiltinName}(lhs.value, rhs.value, false.value)
@@ -327,8 +332,9 @@ extension ${Self} {
 % end
   
 % for Method,op in [('divide', 'div'), ('remainder', 'rem')]:
-  /// Operations that return an overflow bit in addition to a partial result,
-  /// helpful for checking for overflow when you want to handle it.
+  /// Divide `lhs` and `rhs`, returning
+  /// ${'a result' if op == 'div' else 'the remainder'} and a `Bool`
+  /// that is true iff the operation caused an arithmetic overflow.
   @transparent public
   static func ${Method}WithOverflow(lhs: ${Self}, _ rhs: ${Self}) -> (${Self}, overflow: Bool) {
     if rhs == 0 {

stdlib/core/IntegerArithmetic.swift.gyb

@@ -14,9 +14,12 @@
 // Automatically Generated From IntegerArithmeticType.swift.gyb.  Do Not
 // Edit Directly!
 
-% integerBinaryOps = [
-%    (x[:-1], x[-1]) for x in 
-%     'add+ subtract- multiply* divide/ remainder%'.split()]
+%{
+integerBinaryOps = [
+   (x[:-1], x[-1], x[:-1].capitalize(), 'a result') 
+    for x in 'add+ subtract- multiply* divide/'.split()
+] + [ ('remainder', '%', 'Divide', 'the remainder') ]
+}%
 
 /// This protocol is an implementation detail of `IntegerArithmeticType`; do
 /// not use it directly.
@@ -24,8 +27,8 @@
 /// Its requirements are inherited by `IntegerArithmeticType` and thus must
 /// be satisfied by types conforming to that protocol.
 public protocol _IntegerArithmeticType {
-% for name,_ in integerBinaryOps:
-  /// ${name} `lhs` and `rhs`, returning a result and a `Bool` that is
+% for name,_,Action,result in integerBinaryOps:
+  /// ${Action} `lhs` and `rhs`, returning ${result} and a `Bool` that is
   /// true iff the operation caused an arithmetic overflow.
   class func ${name}WithOverflow(lhs: Self, _ rhs: Self) -> (Self, overflow: Bool)
 % end
@@ -35,9 +38,9 @@ public protocol _IntegerArithmeticType {
 public protocol IntegerArithmeticType : _IntegerArithmeticType, Comparable {
   // Checked arithmetic functions.  Specific implementations in
   // FixedPoint.swift.gyb support static checking for integer types.
-% for name,op in integerBinaryOps:
-  /// ${name} `lhs` and `rhs`, trapping in case of arithmetic overflow
-  /// (except in -Ounchecked builds).
+% for name,op,Action,result in integerBinaryOps:
+  /// ${Action} `lhs` and `rhs`, returning ${result} and trapping in case of
+  /// arithmetic overflow (except in -Ounchecked builds).
   func ${op} (lhs: Self, rhs: Self) -> Self
 % end
   
@@ -46,9 +49,9 @@ public protocol IntegerArithmeticType : _IntegerArithmeticType, Comparable {
   func toIntMax() -> IntMax
 }
 
-% for name,op in integerBinaryOps:
-/// ${name} `lhs` and `rhs`, trapping in case of arithmetic overflow
-/// (except in -Ounchecked builds).
+% for name,op,Action,result in integerBinaryOps:
+/// ${Action} `lhs` and `rhs`, returning ${result} and trapping in case of
+/// arithmetic overflow (except in -Ounchecked builds).
 @transparent public
 func ${op} <T: _IntegerArithmeticType>(lhs: T, rhs: T) -> T {
   return _overflowChecked(T.${name}WithOverflow(lhs, rhs))
@@ -78,13 +81,22 @@ func ${op}= <T: _IntegerArithmeticType>(inout lhs: T, rhs: T) {
 /// Its requirements are inherited by `SignedNumberType` and thus must
 /// be satisfied by types conforming to that protocol.
 public protocol _SignedNumberType : Comparable, IntegerLiteralConvertible {
-  // Subtraction is a requirement for SignedNumberType
+  /// Return the difference between `lhs` and `rhs`.
   func - (lhs: Self, rhs: Self) -> Self
 }
 
 // SignedNumberType itself contains only operator requirements having
 // default implementations on the base protocol.
+/// Instances of conforming types can be subtracted, arithmetically
+/// negated, and initialized from `0`.
+///
+/// Axioms:
+///
+/// - `x - 0 == x`
+/// - `-x == 0 - x`
+/// - `-(-x) == x`
 public protocol SignedNumberType : _SignedNumberType {
+  /// Return the result of negating `x`.
   prefix func - (x: Self) -> Self
 
   // Do not use this operator directly; call abs(x) instead
@@ -117,6 +129,7 @@ func ~> <T : _SignedNumberType>(x:T,_:(_Abs, ())) -> T {
   return x < 0 ? -x : x
 }
 
+// FIXME: should this be folded into SignedNumberType?
 /// A type that supports an "absolute value" function.
 public protocol AbsoluteValuable : SignedNumberType {
   class func abs(_:Self) -> Self