[stdlib] update doc-comments and add a code comment

Author: glessard

stdlib/public/core/StringCreate.swift

@@ -316,6 +316,8 @@ extension String {
         unsafe String._uncheckedFromUTF8($0)
       }
 #if os(watchOS) && _pointerBitWidth(_32)
+      // Required for compatibility with some small strings that
+      // may be encoded in the 32-bit slice of watchOS binaries.
       if str._wholeGuts.isSmall,
          str._wholeGuts.count > _SmallString.contiguousCapacity() {
         new.reserveCapacity(_SmallString.capacity + 1)

stdlib/public/core/StringProtocol.swift

@@ -177,17 +177,19 @@ extension StringProtocol {
 
 // Contiguous UTF-8 strings
 extension String {
-  /// Returns whether this string is capable of providing access to
-  /// validly-encoded UTF-8 contents in contiguous memory in O(1) time.
+  /// Returns whether this string's storage contains
+  /// validly-encoded UTF-8 contents in contiguous memory.
   ///
-  /// Contiguous strings always operate in O(1) time for withUTF8 and always
-  /// give a result for String.UTF8View.withContiguousStorageIfAvailable.
+  /// Contiguous strings always operate in O(1) time for withUTF8, always give
+  /// a result for String.UTF8View.withContiguousStorageIfAvailable, and always
+  /// return a non-nil value from `String._utf8Span` and `String.UTF8View._span`.
   /// Contiguous strings also benefit from fast-paths and better optimizations.
-  ///
   @_alwaysEmitIntoClient
   public var isContiguousUTF8: Bool {
     if _guts.isFastUTF8 {
 #if os(watchOS) && _pointerBitWidth(_32)
+      // Required for compatibility with some small strings that
+      // may be encoded in the 32-bit slice of watchOS binaries.
       if _guts.isSmall && _guts.count > _SmallString.contiguousCapacity() {
         return false
       }
@@ -233,13 +235,14 @@ extension String {
 
 // Contiguous UTF-8 strings
 extension Substring {
-  /// Returns whether this string is capable of providing access to
-  /// validly-encoded UTF-8 contents in contiguous memory in O(1) time.
+  /// Returns whether this string's storage contains
+  /// validly-encoded UTF-8 contents in contiguous memory.
   ///
-  /// Contiguous strings always operate in O(1) time for withUTF8 and always
-  /// give a result for String.UTF8View.withContiguousStorageIfAvailable.
+  /// Contiguous strings always operate in O(1) time for withUTF8, always give
+  /// a result for Substring.UTF8View.withContiguousStorageIfAvailable, and
+  /// always return a non-nil value from `Substring._utf8Span` and
+  /// `Substring.UTF8View._span`.
   /// Contiguous strings also benefit from fast-paths and better optimizations.
-  ///
   @_alwaysEmitIntoClient
   public var isContiguousUTF8: Bool { return self.base.isContiguousUTF8 }