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

**URL:** <https://forums.swift.org/t/support-documenting-tuple-return-value-elements-individually-approach-and-implementation/85323>\
**Category:** Swift-DocC\
**Created:** [March 13, 2026, 2:24pm UTC](https://forums.swift.org/t/support-documenting-tuple-return-value-elements-individually-approach-and-implementation/85323 "2026-03-13T14:24:30Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![amanmrya](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/amanmrya/32/44601_2.png) [@amanmrya](https://forums.swift.org/u/amanmrya)\
**Post date:** [March 13, 2026, 2:24pm UTC](https://forums.swift.org/t/support-documenting-tuple-return-value-elements-individually-approach-and-implementation/85323/1 "2026-03-13T14:24:30Z")

</div>

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:

```swift
- 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:

```swift
- 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]](https://github.com/swiftlang/swift-docc/pull/1473)). I'd welcome feedback on both the direction above and the implementation—and happy to adjust based on how people actually document tuple returns.

---

<div class="post-metadata">

**Author:** ![ronnqvist](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ronnqvist/32/20110_2.png) [@ronnqvist](https://forums.swift.org/u/ronnqvist)\
**Post date:** [March 13, 2026, 3:07pm UTC](https://forums.swift.org/t/support-documenting-tuple-return-value-elements-individually-approach-and-implementation/85323/2 "2026-03-13T15:07:39Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![amanmrya](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/amanmrya/32/44601_2.png) [@amanmrya](https://forums.swift.org/u/amanmrya)\
**Post date:** [March 13, 2026, 3:57pm UTC](https://forums.swift.org/t/support-documenting-tuple-return-value-elements-individually-approach-and-implementation/85323/3 "2026-03-13T15:57:10Z")

</div>

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.