Customize documentation for protocol conformances of Encodable and NSSecureCoding

Author: grynspan

Sources/Overlays/_Testing_Foundation/Attachments/Encodable+Test.Attachable.swift

@@ -17,6 +17,38 @@ private import Foundation
 // protocol for types that already support Codable.
 @_spi(Experimental)
 extension Encodable where Self: Test.Attachable {
+  /// Encode this value into a buffer using either [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder)
+  /// or [`JSONEncoder`](https://developer.apple.com/documentation/foundation/jsonencoder),
+  /// then call a function and pass that buffer to it.
+  ///
+  /// - Parameters:
+  ///   - attachment: The attachment that is requesting a buffer (that is, the
+  ///     attachment containing this instance.)
+  ///   - body: A function to call. A temporary buffer containing a data
+  ///     representation of this instance is passed to it.
+  ///
+  /// - Returns: Whatever is returned by `body`.
+  ///
+  /// - Throws: Whatever is thrown by `body`, or any error that prevented the
+  ///   creation of the buffer.
+  ///
+  /// The testing library uses this function when writing an attachment to a
+  /// test report or to a file on disk. The encoding used depends on the path
+  /// extension specified by the value of `attachment`'s ``Testing/Test/Attachment/preferredName``
+  /// property:
+  ///
+  /// | Extension | Encoding Used | Encoder Used |
+  /// |-|-|-|
+  /// | `".xml"` | XML property list | [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder) |
+  /// | `".plist"` | Binary property list | [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder) |
+  /// | None, `".json"` | JSON | [`JSONEncoder`](https://developer.apple.com/documentation/foundation/jsonencoder) |
+  ///
+  /// OpenStep-style property lists are not supported.
+  ///
+  /// - Note: On Apple platforms, if the attachment's preferred name includes
+  ///   some other path extension, that path extension must represent a type
+  ///   that conforms to [`UTType.propertyList`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/propertylist)
+  ///   or to [`UTType.json`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/json).
   public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     let format = try EncodingFormat(for: attachment)
 

Sources/Overlays/_Testing_Foundation/Attachments/NSSecureCoding+Test.Attachable.swift

@@ -17,6 +17,35 @@ public import Foundation
 // NSKeyedArchiver for encoding.
 @_spi(Experimental)
 extension NSSecureCoding where Self: Test.Attachable {
+  /// Encode this object using [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver)
+  /// into a buffer, then call a function and pass that buffer to it.
+  ///
+  /// - Parameters:
+  ///   - attachment: The attachment that is requesting a buffer (that is, the
+  ///     attachment containing this instance.)
+  ///   - body: A function to call. A temporary buffer containing a data
+  ///     representation of this instance is passed to it.
+  ///
+  /// - Returns: Whatever is returned by `body`.
+  ///
+  /// - Throws: Whatever is thrown by `body`, or any error that prevented the
+  ///   creation of the buffer.
+  ///
+  /// The testing library uses this function when writing an attachment to a
+  /// test report or to a file on disk. The encoding used depends on the path
+  /// extension specified by the value of `attachment`'s ``Testing/Test/Attachment/preferredName``
+  /// property:
+  ///
+  /// | Extension | Encoding Used | Encoder Used |
+  /// |-|-|-|
+  /// | `".xml"` | XML property list | [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver) |
+  /// | None, `".plist"` | Binary property list | [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver) |
+  ///
+  /// OpenStep-style property lists are not supported.
+  ///
+  /// - Note: On Apple platforms, if the attachment's preferred name includes
+  ///   some other path extension, that path extension must represent a type
+  ///   that conforms to [`UTType.propertyList`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/propertylist).
   public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     let format = try EncodingFormat(for: attachment)