Some functions are erroneously listed as returning `undefined`

[davidje13]

URL:

https://beta.docs.nodejs.org/net.html#blocklistisblocklistvalue

Browser Name:

Firefox, Chrome

Browser Version:

153.0

Operating System:

macOS 15.7.8

How to reproduce the issue:

The new return type annotations are incorrect if a function has a non-standard description of its return value. An illustrative example is BlockList.isBlockList, which incorrectly shows undefined:

A non-exhaustive list of other examples I've found:

• https://beta.docs.nodejs.org/net.html#new-netsocketaddressoptions shows a return type of void from the constructor
• https://beta.docs.nodejs.org/net.html#blocklisttojson
• https://beta.docs.nodejs.org/net.html#socketaddressparseinput (does not list undefined as a possible return)
• https://beta.docs.nodejs.org/net.html#new-netboundsocketoptions shows a return type of void from the constructor
• https://beta.docs.nodejs.org/buffer.html#new-bufferblobsources-options shows a return type of void from the constructor
• https://beta.docs.nodejs.org/buffer.html#blobbytes
• https://beta.docs.nodejs.org/buffer.html#blobslicestart-end-type
• https://beta.docs.nodejs.org/buffer.html#new-bufferarray (and related constructors)
• https://beta.docs.nodejs.org/buffer.html#new-bufferfilesources-filename-options
• https://beta.docs.nodejs.org/buffer.html#bufferatobdata
• https://beta.docs.nodejs.org/buffer.html#bufferbtoadata
• https://beta.docs.nodejs.org/fs.html#filehandlesymbolasyncdispose should return a Promise, not void
• https://beta.docs.nodejs.org/fs.html#dirsymbolasyncdispose also should return a Promise
• https://beta.docs.nodejs.org/fs.html#new-fsutf8streamoptions
• https://beta.docs.nodejs.org/http.html#new-agentoptions
• https://beta.docs.nodejs.org/http.html#httpgetoptions-callback this should return the same type as the alternative overload beneath it (i.e. http.ClientRequest)
• https://beta.docs.nodejs.org/http.html#httprequestoptions-callback also should return http.ClientRequest
• https://beta.docs.nodejs.org/sqlite.html#new-databasesyncpath-options
• https://beta.docs.nodejs.org/url.html#new-urlinput-base
• https://beta.docs.nodejs.org/url.html#new-urlpattern (and variants)
• https://beta.docs.nodejs.org/url.html#urlpatterntestinput-baseurl should return boolean
• https://beta.docs.nodejs.org/url.html#new-urlsearchparams (and variants)
• https://beta.docs.nodejs.org/url.html#urlformaturlobject (should return a string)

Brian edit: converted these to list items for tracking

Presumably these are issues with the source data, which should be made consistent. But previously the documentation "got away" with it because it didn't try to show this normalised value. In the new documentation, it is probably better to err towards not showing the type in cases where it is not clear, to avoid confusion from mismatches.

Common themes are:

• constructors shown as returning void
• async dispose methods shown as returning void instead of Promise, as required by the interface
• functions with non-standard return text shown as returning undefined
• occasionally functions with multiple possible return types only showing the first option
• some functions which have annotated their return type in the comments instead of in a structured way
• overloaded functions only setting a return type on the last overload

[avivkeller]

Thanks! As a part of moving to the redesign, I should standardize those docs. Unfortunately, I don't think I'll fix this in the preview environment, since it's a source issue, but this issue is good for tracking :-)

[davidje13]

If you can fix them all at source then fantastic! But to be clear the list above is just a tiny fraction of the mismatches, and I've found at least one error on every single documentation page I checked (not all are listed above and I only checked a handful of pages); it may not be practical to hunt them all down individually.

I'd suggest updating the tooling to only show a return type if the method has an annotated return type which it understands. Currently it seems to have some defaults of void if no return type is listed, and undefined if it doesn't understand the return type, which between them make up a large fraction of the errors.

It's perhaps worth noting that although I only listed "old" APIs above (mainly because those are the ones I personally deal with a lot), even relatively new APIs like Web Streams have a large number of issues:

• https://beta.docs.nodejs.org/webstreams.html#readablestreampipetodestination-options (should return Promise<undefined> not undefined)
• https://beta.docs.nodejs.org/webstreams.html#readablestreamvaluesoptions (should return Iterator)
• https://beta.docs.nodejs.org/webstreams.html#readablestreamfromiterable
• https://beta.docs.nodejs.org/webstreams.html#new-readablestreamdefaultreaderstream
• https://beta.docs.nodejs.org/webstreams.html#readablestreamdefaultreadercancelreason
• https://beta.docs.nodejs.org/webstreams.html#readablestreamdefaultreaderread
• (etc.)

[bmuenzenmeyer]

this is fantastic feedback on both accounts, thank you @davidje13 !!