Node: Suggestion: Return type in function declaration & possible option to view types by clicking in doc

[luki]

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

[TimothyGu]

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 like url.parse().

[Fishrock123]

Yeah I'm not really for putting it in the heading either

[luki]

@Fishrock123 A reasoning would be nice

[Fishrock123]

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]

@luki would https://github.com/nodejs/node/pull/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?

[luki]

@gibfahn That sounds amazing!

[lpinca]

Closing this, discussion can continue on the closed thread if needed.

[gibfahn]

The Returns syntax I mentioned is now in the style guide, so feel free to raise PRs to add Returns: anywhere that needs it.