Repository navigation
Suggestion: Return type in function declaration & possible option to view types by clicking in doc #14624
Description
While working with Node.js, I found having the return types of a function (If given) in the function declaration instead of somewhere in the paragraph below it (As seen in the example following) might improve the documentation.
Further on, it would most likely be useful to be able to click on the types. Both suggestions are popular documentation features, example is the Rust Documentation
Here a screenshot of what I mean
Activity
TimothyGu commentedon Aug 4, 2017
Most functions (not
url.parse()it seems, unfortunately) have a "Returns: " bit, like urlSearchParams.entries(). While a good idea, I'm somewhat worried that writing the returned type would crowd the heading too much for a function with long parameter names likeurl.parse().Fishrock123 commentedon Aug 4, 2017
Yeah I'm not really for putting it in the heading either
suesslin commentedon Aug 4, 2017
@Fishrock123 A reasoning would be nice
Fishrock123 commentedon Aug 4, 2017
Easiest argument against it is that that would break links to the docs. Fixing that would probably be non-trivial in the build tooling.
Another is that the return type is already listed.
That being said, while we do have some function with different "argument signatures", it just doesn't operate int he same was a typed language does and as such I'm not certain the same notation is desirable.
Finally, this gets really messy when dealing with async functions that call callbacks with data. (Which most of the significant API is.)
gibfahn commentedon Aug 13, 2017
@Luki would #13769 help?
The arrow syntax works really well in Rust, as that's how return types are shown in the source code, so it's really intuitive.
I think making sure a
- Returns: {Type}is the first thing after the function definition should be pretty clear, WDYT?suesslin commentedon Aug 13, 2017
@gibfahn That sounds amazing!
lpinca commentedon Oct 1, 2017
Closing this, discussion can continue on the closed thread if needed.
gibfahn commentedon Oct 1, 2017
The
Returnssyntax I mentioned is now in the style guide, so feel free to raise PRs to addReturns:anywhere that needs it.