[stdlib] Propagate IntegerArithmeticType docs

184 undocumented public non-operator APIs remain in core

Swift SVN r22227

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