Support documenting tuple return value elements individually (approach and implementation)

Development Swift-DocC
1

I've been looking at Issue #1171, which points out that DocC currently only supports a single block under the Returns section.

For functions that return tuples with named elements, authors usually have to describe the whole return in one paragraph, for example:

- Returns: A tuple containing the quotient and remainder.

That makes it harder to document each element of the tuple return clearly, unlike parameters, where each parameter can be described on its own.

One direction that's been suggested is to support an outline form under Returns, using the same list style as parameters:

- Returns:
  - quotient: The quotient of this value divided by `rhs`.
  - remainder: The remainder with the same sign as the original value.

The idea would be for the Return Value section to render these tuple elements in the same way as Parameters: a list of names and descriptions.

Because this kind of markup can already be written today, the main goal would be to improve how it's interpreted and rendered, and to keep the change additive so existing Returns Documentation (including for tuple returns) keeps working as it does now.

I'm curious what others think from a documentation and authoring perspective:

  • Does documenting tuple return elements this way feel natural when you're writing DocC comments for tuple-returning APIs?

  • Should tuple return elements be presented in the same style as parameters (name + description list), or would you prefer a different presentation?

  • Are there patterns you use today when documenting tuple returns in DocC (e.g., workarounds or conventions) that we could align with or improve on?

I've opened a draft PR that implements this approach ([link]). I'd welcome feedback on both the direction above and the implementation—and happy to adjust based on how people actually document tuple returns.

2 Likes
2

If you ask me this post feels like information that belongs in the PR description rather than a Forum post—especially the parts about how you implemented the changes in your PR.

Typically a Forum post is more appropriate if there is some discussion about how a feature should work from the perspectives of either the person writing the documentation or the person reading the documentation.

3

Thanks for pointing that out. I’ll update the thread to focus more on the discussion perspective and move the implementation details into the PR description.

1 Like