Skip to content

Update DocC symbol references for Attachment _et al._ #822

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
//

extension ABIv0 {
/// A type implementing the JSON encoding of ``Test/Attachment`` for the ABI
/// entry point and event stream output.
/// A type implementing the JSON encoding of ``Attachment`` for the ABI entry
/// point and event stream output.
///
/// This type is not part of the public interface of the testing library. It
/// assists in converting values to JSON; clients that consume this JSON are
Expand Down
8 changes: 4 additions & 4 deletions Sources/Testing/Attachments/Attachable.swift
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@
/// written to disk when a test is run.
///
/// To attach an attachable value to a test report or test run output, use it to
/// initialize a new instance of ``Test/Attachment``, then call
/// ``Test/Attachment/attach(sourceLocation:)``. An attachment can only be
/// attached once.
/// initialize a new instance of ``Attachment``, then call
/// ``Attachment/attach(sourceLocation:)``. An attachment can only be attached
/// once.
///
/// The testing library provides default conformances to this protocol for a
/// variety of standard library types. Most user-defined types do not need to
Expand All @@ -24,7 +24,7 @@
/// sequence of bytes that would be diagnostically useful if a test fails. If a
/// type cannot conform directly to this protocol (such as a non-final class or
/// a type declared in a third-party module), you can create a container type
/// that conforms to ``Test/AttachableContainer`` to act as a proxy.
/// that conforms to ``AttachableContainer`` to act as a proxy.
@_spi(Experimental)
public protocol Attachable: ~Copyable {
/// An estimate of the number of bytes of memory needed to store this value as
Expand Down
10 changes: 5 additions & 5 deletions Sources/Testing/Attachments/AttachableContainer.swift
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@
/// stands in for.
///
/// To attach an attachable value to a test report or test run output, use it to
/// initialize a new instance of ``Test/Attachment``, then call
/// ``Test/Attachment/attach(sourceLocation:)``. An attachment can only be
/// attached once.
/// initialize a new instance of ``Attachment``, then call
/// ``Attachment/attach(sourceLocation:)``. An attachment can only be attached
/// once.
///
/// A type can conform to this protocol if it represents another type that
/// cannot directly conform to ``Test/Attachable``, such as a non-final class or
/// a type declared in a third-party module.
/// cannot directly conform to ``Attachable``, such as a non-final class or a
/// type declared in a third-party module.
@_spi(Experimental)
public protocol AttachableContainer<AttachableValue>: Attachable, ~Copyable {
#if hasFeature(SuppressedAssociatedTypes)
Expand Down
33 changes: 16 additions & 17 deletions Sources/Testing/Attachments/Attachment.swift
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,9 @@ private import _TestingInternals
///
/// Attachments are included in test reports in Xcode or written to disk when
/// tests are run at the command line. To create an attachment, you need a value
/// of some type that conforms to ``Test/Attachable``. Initialize an instance of
/// ``Test/Attachment`` with that value and, optionally, a preferred filename to
/// use when writing to disk.
/// of some type that conforms to ``Attachable``. Initialize an instance of
/// ``Attachment`` with that value and, optionally, a preferred filename to use
/// when writing to disk.
@_spi(Experimental)
public struct Attachment<AttachableValue>: ~Copyable where AttachableValue: Attachable & ~Copyable {
/// Storage for ``attachableValue-7dyjv``.
Expand Down Expand Up @@ -89,7 +89,7 @@ extension Attachment where AttachableValue: ~Copyable {

@_spi(Experimental) @_spi(ForToolsIntegrationOnly)
extension Attachment where AttachableValue == AnyAttachable {
/// Create a type-erased attachment from an instance of ``Test/Attachment``.
/// Create a type-erased attachment from an instance of ``Attachment``.
///
/// - Parameters:
/// - attachment: The attachment to type-erase.
Expand Down Expand Up @@ -163,10 +163,10 @@ extension Attachment where AttachableValue: ~Copyable {
extension Attachment where AttachableValue: AttachableContainer & ~Copyable {
/// The value of this attachment.
///
/// When the attachable value's type conforms to ``Test/AttachableContainer``,
/// the value of this property equals the container's underlying attachable
/// value. To access the attachable value as an instance of `T` (where `T`
/// conforms to ``Test/AttachableContainer``), specify the type explicitly:
/// When the attachable value's type conforms to ``AttachableContainer``, the
/// value of this property equals the container's underlying attachable value.
/// To access the attachable value as an instance of `T` (where `T` conforms
/// to ``AttachableContainer``), specify the type explicitly:
///
/// ```swift
/// let attachableValue = attachment.attachableValue as T
Expand Down Expand Up @@ -230,7 +230,7 @@ extension Attachment where AttachableValue: ~Copyable {

extension Attachment where AttachableValue: ~Copyable {
/// Call a function and pass a buffer representing the value of this
/// instance's ``attachableValue-7dyjv`` property to it.
/// instance's ``attachableValue-2tnj5`` property to it.
///
/// - Parameters:
/// - body: A function to call. A temporary buffer containing a data
Expand All @@ -243,8 +243,8 @@ extension Attachment where AttachableValue: ~Copyable {
///
/// The testing library uses this function when writing an attachment to a
/// test report or to a file on disk. This function calls the
/// ``Test/Attachable/withUnsafeBufferPointer(for:_:)`` function on this
/// attachment's ``attachableValue-7dyjv`` property.
/// ``Attachable/withUnsafeBufferPointer(for:_:)`` function on this
/// attachment's ``attachableValue-2tnj5`` property.
@inlinable public borrowing func withUnsafeBufferPointer<R>(_ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
try attachableValue.withUnsafeBufferPointer(for: self, body)
}
Expand All @@ -265,8 +265,7 @@ extension Attachment where AttachableValue: ~Copyable {
/// - Returns: The path to the file that was written.
///
/// The attachment is written to a file _within_ `directoryPath`, whose name
/// is derived from the value of the ``Test/Attachment/preferredName``
/// property.
/// is derived from the value of the ``Attachment/preferredName`` property.
///
/// If you pass `--experimental-attachments-path` to `swift test`, the testing
/// library automatically uses this function to persist attachments to the
Expand Down Expand Up @@ -302,8 +301,8 @@ extension Attachment where AttachableValue: ~Copyable {
/// - Returns: The path to the file that was written.
///
/// The attachment is written to a file _within_ `directoryPath`, whose name
/// is derived from the value of the ``Test/Attachment/preferredName``
/// property and the value of `suffix`.
/// is derived from the value of the ``Attachment/preferredName`` property and
/// the value of `suffix`.
///
/// If the argument `suffix` always produces the same string, the result of
/// this function is undefined.
Expand Down Expand Up @@ -363,8 +362,8 @@ extension Configuration {
/// - Parameters:
/// - event: The event to handle. This event must be of kind
/// ``Event/Kind/valueAttached(_:)``. If the associated attachment's
/// ``Test/Attachment/fileSystemPath`` property is not `nil`, this
/// function does nothing.
/// ``Attachment/fileSystemPath`` property is not `nil`, this function
/// does nothing.
/// - context: The context associated with the event.
///
/// - Returns: Whether or not to continue handling the event.
Expand Down
2 changes: 1 addition & 1 deletion Sources/Testing/Events/Recorder/Event.Symbol.swift
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ extension Event {
/// The symbol to use when presenting details about an event to the user.
case details

/// The symbol to use when describing an instance of ``Test/Attachment``.
/// The symbol to use when describing an instance of ``Attachment``.
@_spi(Experimental)
case attachment
}
Expand Down