[stdlib] update doc-comment 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,20 @@ 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.utf8._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
       }