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:
geonseokandhxperl authored and GitHub committed 2026-09-11 14:30:00 +00:00
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>(