Enhance documentation for URL attachments. (#1262)

Enhance documentation for
[`Attachment.init(contentsOf:named:sourceLocation:)`](https://developer.apple.com/documentation/testing/attachment/init(contentsof:named:sourcelocation:)).
In particular, provide info on what kind of URLs can be passed in, what
the initializer awaits on, and how to use this (since there's
intentionally no equivalent `record()` overload.)

Resolves #1255.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

---------

Co-authored-by: Graham Lee <[email protected]>

Author: grynspan

Sources/Overlays/_Testing_Foundation/Attachments/Attachment+URL.swift

@@ -36,6 +36,26 @@ extension Attachment where AttachableValue == _AttachableURLWrapper {
   ///
   /// - Throws: Any error that occurs attempting to read from `url`.
   ///
+  /// Use this initializer to create an instance of ``Attachment`` that
+  /// represents a local file or directory:
+  ///
+  /// ```swift
+  /// let url = try await FoodTruck.saveMenu(as: .pdf)
+  /// let attachment = try await Attachment(contentsOf: url)
+  /// Attachment.record(attachment)
+  /// ```
+  ///
+  /// When you call this initializer and pass it the URL of a file, it reads or
+  /// maps the contents of that file into memory. When you call this initializer
+  /// and pass it the URL of a directory, it creates a temporary zip file of the
+  /// directory before reading or mapping it into memory. These operations may
+  /// take some time, so this initializer suspends the calling task until they
+  /// are complete.
+  ///
+  /// - Important: This initializer supports creating attachments from file URLs
+  ///   only. If you pass it a URL other than a file URL, such as an HTTPS URL,
+  ///   the testing library throws an error.
+  ///
   /// @Metadata {
   ///   @Available(Swift, introduced: 6.2)
   ///   @Available(Xcode, introduced: 26.0)