Repository navigation
Some functions are erroneously listed as returning undefined #953
Description
Activity
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 :-)
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
voidif no return type is listed, andundefinedif 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>notundefined) - 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.)
Reacted by Brian Muenzenmeyer- https://beta.docs.nodejs.org/webstreams.html#readablestreampipetodestination-options (should return
this is fantastic feedback on both accounts, thank you @davidje13 !!
- added 2 commits that reference this issue
on Aug 15, 2026 - added a commit that references this issue
on Aug 15, 2026 - added 2 commits that reference this issue
on Aug 18, 2026 - added 3 commits that reference this issue
on Aug 25, 2026 3 remaining items
@AugustinMauroy looks like some have been fixed but not all (or maybe the documentation I'm seeing isn't fully up-to-date with the latest changes?)
e.g. I see these still have incorrect return types on beta.docs.nodejs.org:
- https://beta.docs.nodejs.org/net#blocklisttojson (
voidbut should beBlocklist.rulesas noted in its "returns" section) - https://beta.docs.nodejs.org/buffer#blobbytes (
voidbut should bePromise<Uint8Array>as noted in its description) - https://beta.docs.nodejs.org/url#urlpatternexecinput-baseurl
- https://beta.docs.nodejs.org/url#urlpatterntestinput-baseurl
- https://beta.docs.nodejs.org/webstreams#readablestreamfromiterable
- etc.
- https://beta.docs.nodejs.org/net#blocklisttojson (
we can re-open but should be done on
nodejs/nodebecause issue is on documentation side not renderI guess it can be argued both ways; I suspect this would be closed (or ignored) on
nodejs/nodeas out-of-scope, because the existing documentation does not care if the return type is listed in a semantic way or as a textual description. It's only because of the new signature rendering that this matters.On the rendering side: given the very large number of errors in the new rendering, I'd push for my suggestion from above to be implemented:
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
voidif no return type is listed, andundefinedif it doesn't understand the return type, which between them make up a large fraction of the errors.In any case, all the information is available in the new docs; it's just a bit confusing due to incorrect function signatures.
yeah we shouldn't display anything if info isn't disponible and also warn when not there are missing info
- added 2 commits that reference this issue
on Aug 27, 2026 @davidje13 I assume that at its current state this isn't a doc-kit issue anymore but rather a content issue on nodejs/node doc source, right?
Reacted by Aviv Keller and Brian MuenzenmeyerThe suggestion I made above (quoted in my latest comment) to fail gracefully if the source is not understandable would be a doc-kit issue.
My personal recommended approach would be:
- update doc-kit to fail gracefully rather than fill in
voidorundefinedfor unknown return types: either don't show a signature at all, or show one but without any return type included. That should avoid the majority of the errors and prevent confusion. - once the new documentation is released, you or interested users can start chasing down the individual cases upstream to patch them and get the full signatures
but obviously: it's your project! I'm just reporting that this is an issue and it's pretty likely to cause confusion in its current state. As avivkeller noted above: if it can all be fixed at source then great! But it seems that's been attempted and found to be a bit too big of a task to get through all of them.
- update doc-kit to fail gracefully rather than fill in
- added 2 commits that reference this issue
on Sep 7, 2026 I just went through the rest of the files . some of them still say what they return but without
the{Type}, so they like show up asvoid. readline ~5, webstreams 11, net 2,
stream 1 and may be more . If thats correct I can do them one file at a time.The ones with no Returns line at all are a different one, and will have look on those as well .
- added a commit that references this issue
on Sep 23, 2026 - added a commit that references this issue
on Sep 27, 2026
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 showsundefined:A non-exhaustive list of other examples I've found:
voidfrom the constructorundefinedas a possible return)voidfrom the constructorvoidfrom the constructorPromise, notvoidPromisehttp.ClientRequest)http.ClientRequestbooleanstring)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:
voidvoidinstead ofPromise, as required by the interfaceundefined