@Semigradsky @Renegade334 Do you have any thoughts here> I am unsure what needs to be done to support the scripts in this repo, or if they are even being used.

This includes our JSON-generated API docs, which are used here https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node/scripts/generate-docs to generate the TypeScript types within this repository (and which is used for @types/node)

It's worth clarifying that @types/node only uses Node's JSON docs for updating docblocks for structures that already have definitions; the type definitions themselves aren't generated from the documentation. As such, it's not a critical dependency.

As far as sticking points go, I guess the ones that immediately spring to mind are:

• Text fields are transformed from Markdown to HTML for serialisation in the JSON output, which the @types/node generator then has to convert back to Markdown to be used in docblocks, which is a messy and inevitably imperfect process. It would be more useful to have access to an API document with text fields that are something closer to the source Markdown.
• Where internal links exist in text fields, it's difficult for the generator to work out whether it's dealing with a symbol it can {@link} to, or just an arbitrary internal URL. I don't know if there's any way of adding metadata to improve on this.
• There's an assumption in the Node documentation that it's going to be displayed in order and in continuity: quite often, the documentation text associated with an element makes sense when displayed in the context of its neighbouring elements, but which doesn't scan well when applied in isolation to a TypeScript node. The most frequent culprit is "The following properties are supported:" etc. in the description text for dictionary objects, which looks ugly as a hanging sentence fragment when the description doesn't appear with its associated property list. This is a characteristic of the way the docfiles are written, rather than something specific to the tooling, but it would be desirable for the API output to be formatted such that the text for an individual element always made sense in isolation, and wasn't syntactically dependent on other elements around it.

@SimonSchick might have some more informed insights?

Text fields are transformed from Markdown to HTML for serialisation in the JSON output, which the @types/node generator then has to convert back to Markdown to be used in docblocks, which is a messy and inevitably imperfect process. It would be more useful to have access to an API document with text fields that are something closer to the source Markdown.

• We can provide the descriptions and all the fields in plain Markdown
• Method signatures will still be nicely provided with an API; I believe here's the opportunity for us to craft something that works well for y'all

Where internal links exist in text fields, it's difficult for the generator to work out whether it's dealing with a symbol it can {@link} to, or just an arbitrary internal URL. I don't know if there's any way of adding metadata to improve on this.

Could you give an example? Depending on what it is, we can accommodate you all here.

. This is a characteristic of the way the docfiles are written, rather than something specific to the tooling, but it would be desirable for the API output to be formatted such that the text for an individual element always made sense in isolation, and wasn't syntactically dependent on other elements around it.

That's interesting.

cc @flakey5 can you take note of all of this and ensure we address these points?

For example:

"If the given <code>contextObject</code> is an object, the <code>vm.createContext()</code> method will <a href=\"vm.html#what-does-it-mean-to-contextify-an-object\">prepare that\nobject</a> and return a reference to it so that it can be used in\ncalls to <a href=\"vm.html#vmrunincontextcode-contextifiedobject-options\"><code>vm.runInContext()</code></a> or <a href=\"vm.html#scriptrunincontextcontextifiedobject-options\"><code>script.runInContext()</code></a>. [...]"

This contains two hyperlinks to API functions, one to vm.runInContext() and one to vm.Script#runInContext(). There's no straightforward way of parsing those links to work out whether the link targets an API identifier or not, and if so, which identifier it's pointing to.

@types/node's tooling attempts to parse those into JSDoc internal @links to identifiers in the same module, but doesn't have much to go off. To be honest, this feature could probably just be dispensed with – it's imperfect, and doesn't add very much to the package's usability – but since it pertains to consuming the API JSON, thought it would be worth mentioning.

In an ideal world, internal documentation links targeting the entry for an API identifier would be somehow metadata-labelled with that identifier, to make it easier for a parser to identify that relationship. That would probably necessitate wholesale changes to the source docs, however, for likely not a great deal of overall benefit.

I see, on the new format we intend to make the JSOn content to be plain (but parsed) Markdown.

Is it correct to assume that the main objective of your script is to generate js-docs? What if the new format followed a js-doc topology?

Assume the new format is an array (flat) JavaScript objects where the keys are JSdoc (https://jsdoc.app/) "block tags" such as @type, @param, etc... Resulting in something lke:

[
  {
    "id": "uniqueId",
    "slug": "uniqueSlug",
    "@name": "jsdoc compatible name",
    "@namespace": "nodejs module name",
    "@param": [{...}],
    ...
  }
]

How would you feel if the new API follows something like this (?) -- note that we would still provide the current one.

(Note that @ prefixed keys are jsdoc keys and non-@ prefixed would be internal keys

Is it correct to assume that the main objective of your script is to generate js-docs?

Aye, that's all it's used for.

What if the new format followed a js-doc topology?

Sounds good to me. Doesn't sound like it'd impact on that specific question (parsing internal links within text blocks) but from an overall standpoint, it seems like it'd fit this package's usage case well.

I believe the parsing of links wouldn't be needed as we would do that for you :) with the @link notation.