stdlib: doc comments: clarify the behavior of algorithms on SequenceType

These clarifications were requested in API review.

Swift SVN r27951

stdlib/public/core/SequenceAlgorithms.swift.gyb

@@ -57,7 +57,7 @@ else:
 
 extension SequenceType ${"" if preds else "where Self.Generator.Element : Comparable"} {
 
-  /// Returns the minimum element in `self`.
+  /// Returns the minimum element in `self` or `nil` if the sequence is empty.
   ///
   /// - complexity: O(count(elements))
   /// ${orderingRequirement}
@@ -78,7 +78,7 @@ extension SequenceType ${"" if preds else "where Self.Generator.Element : Compar
     return result
   }
 
-  /// Returns the maximum element in `self`.
+  /// Returns the maximum element in `self` or `nil` if the sequence is empty.
   ///
   /// - complexity: O(count(elements))
   /// ${orderingRequirement}
@@ -116,12 +116,14 @@ extension SequenceType ${"" if preds else "where Self.Generator.Element : Equata
 if preds:
   comment = """
   /// Return true iff `self` begins with elements equivalent to those of
-  /// `other`, using `isEquivalent` as the equivalence test.
+  /// `other`, using `isEquivalent` as the equivalence test.  Return true if
+  /// `other` is empty.
   ///
   /// Requires: `isEquivalent` is an [equivalence relation](http://en.wikipedia.org/wiki/Equivalence_relation)"""
 else:
   comment = """
-  /// Return true iff the the initial elements of `s` are equal to `prefix`."""
+  /// Return true iff the the initial elements of `self` are equal to `prefix`.
+  /// Return true if `other` is empty."""
 }%
   ${comment}
   final public func _prext_startsWith<
@@ -221,12 +223,22 @@ if preds:
   /// Return true iff `self` precedes `other` in a lexicographical ("dictionary")
   /// ordering, using `isOrderedBefore` as the comparison between elements.
   ///
+  /// - note: This method implements the mathematical notion of lexicographical
+  /// ordering, which has no connection to Unicode.  If you are sorting strings
+  /// to present to the end-user, you should use `String` APIs that perform
+  /// localized comparison.
+  ///
   /// Requires: `isOrderedBefore` is a [strict weak ordering](http://en.wikipedia.org/wiki/Strict_weak_order#Strict_weak_orderings)
   /// over the elements of `self` and `other`."""
 else:
   comment = """
   /// Return true iff `self` precedes `other` in a lexicographical ("dictionary")
-  /// ordering, using "<" as the comparison between elements."""
+  /// ordering, using "<" as the comparison between elements.
+  ///
+  /// - note: This method implements the mathematical notion of lexicographical
+  /// ordering, which has no connection to Unicode.  If you are sorting strings
+  /// to present to the end-user, you should use `String` APIs that perform
+  /// localized comparison."""
 }%
 
   ${comment}