Support documenting tuple return value elements individually

[d-ronnqvist]

Feature Name

Support documenting tuple return value elements individually

Description

Currently, return value documentation in DocC applies to the entire return value as a whole. This makes sense for functions and methods that return a single value but for functions and methods that return tuples (especially tuples with named elements) it mean that the same paragraph has to describe both values and describe the tuple structure in the content.

For example, the quotientAndRemainder(dividingBy:) method in Swift documents its return value as:

A tuple containing the quotient and remainder of this value divided by rhs. The remainder has the same sign as lhs.

Similarly, code in DocC itself uses the "a pair of ..." phrase to describe tuple return values:

/// ...
/// - Returns: A pair of the parsed path components and a flag that indicate if the documentation link is absolute or not.
static func parse(path: String) -> (components: [PathComponent], isAbsolute: Bool) 

/// ...
/// - Returns: A pair of the matching elements and the remaining elements, that didn't match.
func categorize<Result>(where matches: (Element) -> Result?) -> (matching: [Result], remainder: [Element]) 

In cases like this it could be helpful to be able to document each element of the tuple return value individually using a syntax similar to the way parameters are documented. For example:

/// ...
/// - Returns:
///   - quotient: the quotient of this value divided by `rhs`.
///   - remainder: the remainder of this value divided by `rhs` with the same sign as the original value.
func quotientAndRemainder(dividingBy rhs: Self) -> (quotient: Self, remainder: Self)

/// ...
/// - Returns:
///   - component: the parsed path components.
///   - isAbsolute: a flag that indicate if the documentation link is absolute or not.
static func parse(path: String) -> (components: [PathComponent], isAbsolute: Bool) 

/// ...
/// - Returns: 
///   - matching: the elements that match the predicate.
///   - remainder: the elements that don't match the predicate.
func categorize<Result>(where matches: (Element) -> Result?) -> (matching: [Result], remainder: [Element]) 

Note: It's possible to write documentation markup like this today but the list items in the return value aren't presented the same as the items for the parameter documentation:

---

DocC already knows how many elements the tuple return value contains, so it should be possible to raise warnings if the return value documentation describes too many or too few individual return values.

It's important that this is an additive change so that existing documentation for tuple return value don't change behavior or result in warnings.

In some cases the developer might also prefer to continue to document all tuple elements of the return value together. That should continue to be supported.

Motivation

See the description above for example use cases of documenting tuple return value elements individually.

Importance

This is a fairly unimportant enhancement. It doesn't enable any new use-cases and the markup for this is already supported but it doesn't render as well as it could on the page.

Alternatives Considered

No response

[GunjanRawat26]

Hey @d-ronnqvist , I would like to work on this. Since this is my first issue, could you point me to the relevant code I should look at?

[d-ronnqvist]

Absolutely. Here are a few places to start with:

• TaggedListItemExtractor.visitListItem(_:) is where DocC parses the markup in to a list of Return structures, as well as all the other list items like parameters, throws, etc.

• ReturnsSectionTranslator is where DocC creates JSON data for the renderer for each return sections. It's possible that we'd need a new type of render section to display this. Maybe it's possible to unify some of the render sections. It looks to me like ParametersRenderSection and PossibleValuesSection are very similar already.

  Maybe it's possible to define a more abstract render section kind that includes the section title which could be used for all 3 (parameters, possible values, and named tuple return value elements).
  /cc @mportiz08

• ParametersAndReturnValidator.makeReturnsSectionVariants(_:_:documentedSymbolKind:swiftSymbolKind:hasDocumentedParameters:) is where DocC checks the documented return value and warns if there's return value documentation for a function that only returns void. This code also creates specialized return value sections for each (programming) language if the symbol has different return values in different language representations (for example Void in Swift but BOOL in Objective-C).

In each of these places it could be good to compare the return value structures and processing to the parameters processing since parameter documentation already has individual named elements.

[d-ronnqvist]

Some of this code is public API. We don't want to break that unless it's necessary (see Introducing source breaking changes in CONTRIBUTING.md).

It's something to be aware of but you don't need to worry too much about it up front. We can iterate together in the PR to add deprecations and compatibility wrappers to avoid any source breaking changes, if there are any.

[thisismanan]

hey @d-ronnqvist i was trying to work on this, this is my first time trying to contribute, i was just wondering how could i test locally if my implementation works, i would appreciate any guidance you could give

[d-ronnqvist]

How I'd go about testing this would depend on which part I'm working on. If you're asking about visually verifying the results end-to-end then I that would probably involve:

• defining a public function with a tuple return type in a new package
• writing a documentation comment for that function that documents each tuple element
• building documentation for that package to get the symbol graph output
• passing that symbol graph output to the preview command of your locally built docc executable
• navigating to the rendered preview page to see how the return value documentation looks on the page.

That said, if you're just getting started working on this, it will probably be easier to work on and verify a smaller piece before trying to verify the end-to-end result.

One place to start could be in ReturnsSectionTranslator where you could hardcode some structure (which doesn't yet come from the documentation markup) to see if it's possible to render the name and documentation for each individual return value or if that requires a new type or render section. Once you know what data the ReturnsSectionTranslator needs to output you can write an automated test for that. For here you could either:

• gradually work your way backwards to TaggedListItemExtractor.visitListItem(_:) where the markup for return value sections is parsed
• jump to TaggedListItemExtractor.visitListItem(_:) (where the markup for return value sections is parsed) and gradually work your way forward until you reach the ReturnsSectionTranslator again.

Once you have you've connected the updated markup parsing code with the updated rendering code you'll be able to verify the happy case end-to-end. That's what some jokingly say is the first 90% done with an additional 90% remaining.

We would want to raise warnings if the developer documented a tuple return value for a function that doesn't return a tuple or documented three tuple elements when the function only returns a tuple with two elements. DocC does this sort of validation and warnings in ParametersAndReturnValidator.makeReturnsSectionVariants(_:_:documentedSymbolKind:swiftSymbolKind:hasDocumentedParameters:).

[thisismanan]

understood, will try working through this issue, with the points you have put, thank you!