doc: @types/node JSDoc integration - guidance and call to collaboration

[SimonSchick]

Rationale

NodeJS docs are currently not well integrated into any IDEs which generally slows down developers as they have to consult the official documentation website (which may go down) or an offline copy, a mental context switch is required when wanting to look up even small details such as a functions description/behaviour.

@types/node has made NodeJS application development significantly faster, safer and easier (minus initial setup 😃 ) due to TypeScript's inherit properties and has already resolved a good amount of the aforementioned context-switches, I however believe there is still a lot of potential to improve this.

Documentation integration and upkeep in the type definitions has been a major chore and was often done very inconsistently (I'm very guilty of this).

In order to improve the development experience and reduce the reliance of developers on mutliple sources NodeJS documentation can and should be more tightly coupled/integrated with the current @types/node distribution.

Work

Over the last couple of weeks I've invested a fair amount of time writing some scripts that incorporate a very large amount of existing NodeJS documentation into the current TypeScript definition.

The current progress of this effort can be inspected here DefinitelyTyped/DefinitelyTyped#54417

Asks

• Guidance on how/when credit/license should be give the copying of others people work is quite substantial.
• Invite people to collaborate and get input on the current integration, the current implementation is rather simplistic and rather crude.
• Discuss the structural issues of the current JSON doc output as I've had to perform a lot of quirky rewrites and fixes of the JSON doc in order to be able to work with it.

[Trott]

• Discuss the structural issues of the current JSON doc output as I've had to perform a lot of quirky rewrites and fixes of the JSON doc in order to be able to work with it.

Fixes for the JSON doc output are welcome. You can PR them in here. Or open specific issues. The code that generates the JSOn docs is in tools/doc/json.mjs.

[SimonSchick]

I vaguely remember some efforts of changing the current format to something that is used by another package, maybe electron(?) but cannot find the associated thread/issue.
Do you perhaps have a link to that?

I want to avoid working on something only for it to be tossed soon after, once I got the initial aforementioned PR in DT out I will look into fixing some of the structural un-soundness of the current docs (iirc they boil down to markdown formatting issues.

[Trott]

I vaguely remember some efforts of changing the current format to something that is used by another package, maybe electron(?) but cannot find the associated thread/issue.
Do you perhaps have a link to that?

nodejs/node#32206

[Trott]

• Guidance on how/when credit/license should be give the copying of others people work is quite substantial.

I'm not sure if you're talking about Node.js docs or other work, but if Node.js core stuff, it's all MIT licensed so the licensing and even crediting should be pretty straightforward.

[SimonSchick]

I'm a little out of the loop/practise but would it be sufficient to copy/insert this section into the index.d.ts file that is shipped?

[Trott]

I am not a lawyer so this is not legal advice blah blah blah meow meow meow, but yes, I am under the impression that including that notice would be sufficient.

[Trott]

• Invite people to collaborate and get input on the current integration, the current implementation is rather simplistic and rather crude.

You've probably noticed this, but just in case: There has been an effort lately to add JSDoc typings for the Node.js internal modules, so that might be useful. I believe @VoltrexMaster has been doing much (most? all?) of the work there.

[SimonSchick]

I saw a couple of PRs but I'm uncertain if they had any impact on doc generation so far, I will look into this!