[stdlib] Doc comments and parameter naming, NFC

Fixes <rdar://problem/17998481>

Swift SVN r21204

stdlib/core/Arrays.swift.gyb

@@ -309,16 +309,29 @@ extension ${Self} : ArrayType {
   
   //===--- algorithms -----------------------------------------------------===//
 
+  /// Interpose `self` between each consecutive pair of `elements`,
+  /// and concatenate the elements of the resulting sequence.  For
+  /// example, `[-1, -2].join([[1, 2, 3], [4, 5, 6], [7, 8, 9]])`
+  /// yields `[1, 2, 3, -1, -2, 4, 5, 6, -1, -2, 7, 8, 9]`
   public func join<
       S : SequenceType where S.Generator.Element == ${Self}<T>
   >(elements: S) -> ${Self}<T> {
     return Swift.join(self, elements)
   }
 
+  /// Return the result of repeatedly calling `combine` with an
+  /// accumulated value initialized to `initial` and each element of
+  /// `self`, in turn, i.e. return
+  /// `combine(combine(...combine(combine(initial, self[0]),
+  /// self[1]),...self[count-2]), self[count-1])`.
   public func reduce<U>(initial: U, combine: (U, T)->U) -> U {
     return Swift.reduce(self, initial, combine)
   }
 
+  /// Sort `self` in-place according to `isOrderedBefore`.  Requires:
+  /// `isOrderedBefore` induces a `strict weak ordering
+  /// <http://en.wikipedia.org/wiki/Strict_weak_order#Strict_weak_orderings>`__
+  /// over the elements.
   public mutating func sort(isOrderedBefore: (T, T)->Bool) {
     return withUnsafeMutableBufferPointer {
       me in Swift.sort(&me, isOrderedBefore)
@@ -326,6 +339,11 @@ extension ${Self} : ArrayType {
     }
   }
 
+  /// Return a copy of `self` that has been sorted according to
+  /// `isOrderedBefore`.  Requires: `isOrderedBefore` induces a
+  /// `strict weak ordering
+  /// <http://en.wikipedia.org/wiki/Strict_weak_order#Strict_weak_orderings>`__
+  /// over the elements.
   public func sorted(isOrderedBefore: (T, T)->Bool) -> ${Self} {
     var result = self
     result.sort(isOrderedBefore)