search

nodejs / api-docs-tooling

Node.js's tooling for API generation
https://nodejs.org/api
MIT License
3 stars 4 forks source link

Add `json` generator #57

Open ovflowd opened 1 month ago

ovflowd commented 1 month ago

This issue details the creation of the json generator. Unlike the json-simple generator that writes all content on a predefined single file, the json generator works like the other generators (i.e., legacy-HTML); it writes a JSON file for each module.

The json generator follows a hierarchy of the module (being a nested JSON (a JSON tree, where each depth level increases the nested-ness (as we have on the current https://nodejs.org/api/*.json format)

We also need to parse a section entry API options (params, return types, etc.) similarly as it is done on the current JSON format; There's room for improvement here and an opportunity to better the format.

There are other little pieces. For example, the metadata within node.updates should be flattened out to be properties directly of the node entry instead of an array.

I also believe the signature transformation (options) of methods/classes/constructors can be part of a centralized process until it can be reused or applied directly at the ApiDocMetadataEntry as a new property.

I also believe we could follow the JSDoc schema, which would be completely different from the current one but completely easy for downstream users to consume. This is just an idea, but feels good.

flakey5 commented 6 days ago

I also believe we could follow the JSDoc schema

JSDoc or JSON schema?

Also, starting some preliminary work on what the schema should look like here

ovflowd commented 6 days ago

I also believe we could follow the JSDoc schema

JSDoc or JSON schema?

Also, starting some preliminary work on what the schema should look like here

JSDoc schema :) like the properties of each object within the JSON match the properties that JSdoc schema supports.

ovflowd commented 6 days ago

Notes here from downstream discussion: https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/70298