[stdlib] document some deprecated initializers

Author: glessard

stdlib/public/core/CString.swift

@@ -52,6 +52,19 @@ extension String {
     }
   }
 
+  /// Creates a new string by copying the null-terminated UTF-8 data referenced
+  /// by the given array.
+  ///
+  /// If `cString` contains ill-formed UTF-8 code unit sequences, this
+  /// initializer replaces them with the Unicode replacement character
+  /// (`"\u{FFFD}"`).
+  ///
+  /// Note: This initializer is deprecated. Use the initializer
+  ///       `String.init(decoding: array, as: UTF8.self)` instead,
+  ///       remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///     An array containing a null-terminated sequence of UTF-8 code units.
   @inlinable
   @_alwaysEmitIntoClient
   @available(swift, deprecated: 6, message: "Use String(decoding: array, as: UTF8.self) instead")
@@ -102,6 +115,18 @@ extension String {
       UnsafeBufferPointer(start: nullTerminatedUTF8, count: len)).0
   }
 
+  /// Creates a new string by copying the null-terminated UTF-8 data referenced
+  /// by the given array.
+  ///
+  /// This is identical to `init(cString: [CChar])` but operates on
+  /// an unsigned sequence of bytes.
+  ///
+  /// Note: This initializer is deprecated. Use the initializer
+  ///       `String.init(decoding: array, as: UTF8.self)` instead,
+  ///       remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///     An array containing a null-terminated UTF-8 code unit sequence.
   @inlinable
   @_alwaysEmitIntoClient
   @available(swift, deprecated: 6, message: "Use String(decoding: array, as: UTF8.self) instead")
@@ -205,6 +230,18 @@ extension String {
     self = str
   }
 
+  /// Creates a new string by copying and validating the null-terminated UTF-8
+  /// data referenced by the given array.
+  ///
+  /// This initializer does not try to repair ill-formed UTF-8 code unit
+  /// sequences. If any are found, the result of the initializer is `nil`.
+  ///
+  /// Note: This initializer is deprecated. Use the initializer
+  ///       `String.init?(validating: array, as: UTF8.self)` instead,
+  ///       remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter nullTerminatedUTF8:
+  ///     An array containing a null-terminated sequence of UTF-8 code units.
   @inlinable
   @_alwaysEmitIntoClient
   @available(swift, deprecated: 6, message: "Use String(validating: array, as: UTF8.self) instead")
@@ -221,6 +258,18 @@ extension String {
     self = string
   }
 
+  /// Creates a new string by copying and validating the null-terminated UTF-8
+  /// data referenced by the given array.
+  ///
+  /// This initializer does not try to repair ill-formed UTF-8 code unit
+  /// sequences. If any are found, the result of the initializer is `nil`.
+  ///
+  /// Note: This initializer is deprecated. Use the initializer
+  ///       `String.init?(validating: array, as: UTF8.self)` instead,
+  ///       remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameter cString:
+  ///     An array containing a null-terminated sequence of UTF-8 code units.
   @inlinable
   @_alwaysEmitIntoClient
   @available(swift, deprecated: 6, message: "Use String(validating: array, as: UTF8.self) instead")
@@ -424,6 +473,22 @@ extension String {
     self = String.decodeCString(nullTerminatedCodeUnits, as: sourceEncoding)!.0
   }
 
+  /// Creates a new string by copying the null-terminated sequence of code units
+  /// referenced by the given array.
+  ///
+  /// If `nullTerminatedCodeUnits` contains ill-formed code unit sequences, this
+  /// initializer replaces them with the Unicode replacement character
+  /// (`"\u{FFFD}"`).
+  ///
+  /// Note: This initializer is deprecated. Use the initializer
+  ///       `String.init(decoding: array, as: Encoding.self)` instead,
+  ///       remembering that "\0" is a valid character in Swift.
+  ///
+  /// - Parameters:
+  ///   - nullTerminatedCodeUnits: An array containing a null-terminated
+  ///     sequence of code units encoded in `sourceEncoding`.
+  ///   - sourceEncoding: The encoding in which the code units should be
+  ///     interpreted.
   @inlinable
   @_alwaysEmitIntoClient
   @available(swift, deprecated: 6, message: "Use String(decoding: array, as: Encoding.self) instead")