Repository navigation
Making it easier for DTS consumers #441
Description
This was discussed in today's Web Team Meeting.
Supersedes: #437
We'd like to make our AST, and possibly a generator, to make it easy to consume Node.js docs by the DTS maintainers. We want them to have a good DX.
As discussed in today's meeting, this means finding and resolving quirks that require these maintainers to manually scour our documentation, which, on it's own, has many fallacies.
Activity
Renegade334 commentedon Oct 10, 2025
Some musings on the state of play, as discussed. Apologies for the slight tardiness.
I've deliberately omitted things that cause us obstacles, but which aren't really fixable within the documentation system that exists. Hopefully everything here is either actionable, or at the very least food for thought.
Objects
{Object}types, with no elaboration. In rare occasions, the API in question is truly agnostic as to the object being accepted or returned. In most of these cases, however, the shape of the output or expected input is known but is described verbally, which isn't useful from a typing perspective.exactOptionalPropertyTypescompiler option enabled.?: T) and those that are unconditionally present but might be undefined (: T | undefined) in TypeScript whenexactOptionalPropertyTypesis enabled, and there is absolutely no way to express this in the docs at present.{Function}qualified with its parameter and return types other than verbally, and it's unclear whether there is a canonical convention for this.Buffers
validateBuffer(), but it's extremely variable as to which APIs are documented as such.{ArrayBuffer}actually refer to "any array buffer" (ie.{ArrayBuffer} | {SharedArrayBuffer}), but this is again variably documented.Promises
{Promise}, with a verbal description of what the Promise actually resolves to. This isn't useful for us.Promise<...>) to unlock improvements here.Arrays
{Array}, which aren't useful.(string | URL)[]is expressed asstring[] | URL[], which isn't accurate.Array<string | URL>) in order to be improved upon.I know I've said it a lot, but I feel like it's worth reiterating: the greatest hurdle for DT is the robustness and accuracy of the source material, not the tooling itself. However, that's not to say that QOL improvements wouldn't be well-received.
avivkeller commentedon Oct 10, 2025
Thank you! We have JSConf and the Collaborator Summit next week, so I can definitely get some input from the core collaborators!
Renegade334 commentedon Oct 10, 2025
The existential question at the heart of all of this is what the documentation is intended to be. Is it a somewhat relaxed, best-effort human guidebook, or is it intended to be a robust, structured resource that's machine-consumable? At the moment, it seems to be a hybrid of both, which is where a lot of the friction lies.
I suppose a related question is whether the project and associated documentation have grown to the extent that it's worth considering documenting the API in a structured language, rather than a set of glorified READMEs... 😉
flakey5 commentedon Oct 11, 2025
Thank you @Renegade334!
I'm hoping that with the new JSON representation for the docs (re #214, #287) solves some of the QOL issues you mentioned, but regardless there's still some outstanding.
Iirc, one of the next steps once all the new tooling is in Node core is to review the actual structure of the docs and see what changes would be good to make, which hopefully also means resolving even more of the issues you mentioned
avivkeller commentedon Oct 12, 2025
(I'm marking this "Blocked" until we integrate the new tooling into core, since, once that's done, we have a lot more control over that content)