mirror of
https://github.com/apple/swift-nio
synced 2026-11-22 04:30:41 +00:00
Fix the Returns callout on DispatchQueue.asyncWithFuture (#3740)
### What's wrong `Sources/NIOCore/DispatchQueue+WithFuture.swift:30`, the return-value line of the public `DispatchQueue.asyncWithFuture(eventLoop:_:)`: ```swift /// - returns a new `EventLoopFuture<ReturnType>` with value returned by the `block` parameter. ``` There is no colon after `returns`, so DocC does not recognise it as a `- Returns:` callout. The method renders **no Return Value section**; the sentence falls into the Discussion as a stray bullet instead. Two further identifiers in that same sentence do not exist on this method: - `ReturnType` — the generic parameter is `NewValue` (`asyncWithFuture<NewValue: Sendable>`). - `block` — the closure parameter is `callbackMayBlock`. The `- Parameters:` block directly above it is correct and unaffected. ### Reproduction I could not build NIO to render this page (see Testing below), so I reproduced the DocC behaviour on a standalone module carrying this method's doc comment **verbatim**, alongside a copy with only the colon restored. Same file, same DocC, so the callout spelling is the only variable: ``` broken(eventloop:_:).json HEADING: Discussion codeListing ... unorderedList: "returns a new `EventLoopFuture<ReturnType>` with value returned by the `block` parameter." fixed(eventloop:_:).json HEADING: Return Value paragraph: "A new `EventLoopFuture<NewValue>` with value returned by the `callbackMayBlock` parameter." ``` The broken form produces a `Discussion` heading with the text demoted to a list item. The fixed form produces a `Return Value` heading with a proper paragraph. Commands, if you want to confirm it against the real module: ``` swift build --target NIOCore \ -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc /tmp/sg xcrun docc convert --fallback-display-name NIOCore \ --fallback-bundle-identifier org.swift.NIOCore \ --additional-symbol-graph-dir /tmp/sg --output-path /tmp/out.doccarchive ``` then read `data/documentation/niocore/dispatchqueue/asyncwithfuture(eventloop:_:).json`. Worth noting: **DocC emits no diagnostic for this.** `docc convert` exits 0 with an empty warning list, so nothing in a normal build or docs check surfaces it. The rendered output is the only evidence. ### Scope, and a judgement call One line. This is the only occurrence in the repository — I grepped all of `Sources/` for `- returns`/`- Returns` without a colon and for backticked parameter names, and there is nothing else. **The judgement call is fixing `ReturnType` and `block` in the same change.** The narrower alternative is to add only the colon and leave the two names for a separate PR. I did not do that, because restoring the colon is exactly what *promotes this sentence from invisible to visible* — shipping the colon alone would put two identifiers that do not exist on the method onto the rendered page for the first time. Correcting them is what makes the fix an improvement rather than a regression in visible accuracy. If you would rather have the colon alone and handle the names separately, say so and I will split it. ### Testing **I did not run NIO's test suite, and I want to be straightforward about why rather than imply a green run.** The machine I am working on is disk-constrained and a NIO build did not fit; that is a limitation on my side, not a judgement that the suite is unnecessary. What I did verify: - The defect and its uniqueness by reading, against `main` at `8c063f043d94c120d0f8d6303ef4fc7918e3561d`. - The identifier mismatches against the actual declaration in the same file. - DocC's parsing behaviour, via the standalone reproduction above (real output, not asserted). - The new line is 110 characters, within the repository's configured `lineLength` of 120. This is a comment-only change to a doc comment; it cannot affect compiled behaviour. CI will confirm the build and the format check. ### Disclosure This change was written with AI assistance. The DocC output above is real output from my machine, not generated text. Co-authored-by: hxperl <16929288+hxperl@users.noreply.github.com>
This commit is contained in:
1 parent
8c063f043d
commit
a8a8f22d99
1 file changed
+1
-1
@@ -27,7 +27,7 @@ extension DispatchQueue {
|
||||
/// - Parameters:
|
||||
/// - eventLoop: the `EventLoop` on which to processes the IO / task specified by `callbackMayBlock`.
|
||||
/// - callbackMayBlock: The scheduled callback for the IO / task.
|
||||
/// - returns a new `EventLoopFuture<ReturnType>` with value returned by the `block` parameter.
|
||||
/// - Returns: a new `EventLoopFuture<NewValue>` with value returned by the `callbackMayBlock` parameter.
|
||||
@inlinable
|
||||
@preconcurrency
|
||||
public func asyncWithFuture<NewValue: Sendable>(
|
||||
|
||||
Reference in new issue
Block a user