Node: doc: list the stability status of each API in one place?

[joyeecheung]

Right now each API has their own page with their stability index, but AFAIK there is not a central place where you can find the stability status of all the APIs at a glance (correct me if I am wrong). It may be useful to have a list somewhere in https://github.com/nodejs/node/blob/master/doc/api/documentation.md#stability-index

[robertoschiavone]

I can pick this one

[hyeonQ]

I expect to make the first commit of nodejs. I can gather the stability of APIs in one place.

[vsemozhetbyt]

I suppose we may need to automate this with doc tools scripts. Otherwise, each deprecation and API addition will need to be addressed in this list manually which may be error-prone.

[joyeecheung]

I suppose we may need to automate this with doc tools scripts.

@vsemozhetbyt Good idea. Can you leave a few pointers? I only have a vague idea that people who want to hack on this should start in https://github.com/nodejs/node/tree/master/tools/doc

Also cc @nodejs/documentation

[vsemozhetbyt]

Recently, we change our toolchain a bit, so maybe @rubys can give some hints.

I think we have at least two options:

1. Parse TOC in all.html. TOC entries already have class="stability_*" attributes for deprecated and experimental stability. But we may need to distinguish API headers from other headers here (by a RegExp?).

2. Parse all.json. It will be easier to distinguish API entries from other entries there (look for "classes", "methods", and "properties" fields), and the field "stability" also exists there.

[rubys]

I recommend that all.json approach. The input data is already parsed. Iterate over the structure, producing output as you go. The tool should go in the tools/doc/ directory, and added to the Makefile as depending on out/doc/api/all.json. As we seem to have volunteer(s), I'll review and coach as needed.

[hyeonQ]

I hope to try this work.
So far as I understand it, there is a need to gather the stability of the various APIs of node.js and It is a better to parse all.json.
By the way, I am confused which files need to be modified and where to put gathered things

[huhgawz]

@HYU-LeeHG are you actively working on this issue? If not, it would be great to take it

[shobhitchittora]

@rubys I went ahead wrote a script to get all the stability keys from the json mentioned.

| API | Stability |
| --- | --------- |
| assert | (2) Stable |
| async_hooks | (1) Experimental |
| buffer | (2) Stable |
| cluster | (2) Stable |
| console | (2) Stable |
| crypto | (2) Stable |
| dns | (2) Stable |
| dns_promises_api | (1) Experimental |
| Events | (2) Stable |
| fs | (2) Stable |
| fs_promises_api | (1) Experimental |
| http | (2) Stable |
| http/2 | (1) Experimental |
| https | (2) Stable |
| inspector | (1) Experimental |
| module | (2) Stable |
| os | (2) Stable |
| path | (2) Stable |
| performance_timing_api | (1) Experimental |
| querystring | (2) Stable |
| readline | (2) Stable |
| repl | (2) Stable |
| stream | (2) Stable |
| string_decoder | (2) Stable |
| timers | (2) Stable |
| tls_(ssl) | (2) Stable |
| trace_events | (1) Experimental |
| tty | (2) Stable |
| dgram | (2) Stable |
| url | (2) Stable |
| util | (2) Stable |
| serialization_api | (1) Experimental |
| vm | (2) Stable |
| vm.SourceTextModule | (1) Experimental |
| worker_threads | (1) Experimental |
| zlib | (2) Stable |

What are your thoughts on organizing this? What can be the next steps?

[adarshsaraogi]

can i take this issue

[shuhei]

Hi, I was looking for a good first issue and ran into this issue.

So https://github.com/shobhitchittora/node/commit/b0c54610ea7475a542f904e9e68ee62a4d88c18e by @shobhitchittora already collects stability statuses and outputs them into a table. The problem is how to put it into the docs. Possible options would be:

1. Output the table as a separate file like out/doc/api/stability_index.md (also .html and .json?) with the tool, and have a link to the file from doc/api/documentation.md
2. Insert the table into out/doc/api/documentations.md, .html and .json with the tool
3. Update doc/api/documentation.md with the tool and commit the change into git

The option 1 seems easiest to me. What do you think? @joyeecheung @rubys @shobhitchittora

[joyeecheung]

@shuhei I'd prefer we do option 2 if possible, but we could also implement option 1 first (in any cases I can imagine a stability.json hosted on our website being useful for consumers)

[RamirezAlex]

If no one is working on it I can give it a try.

[martin-dimitrov13]

Would this include only the top level API's (as in @shobhitchittora 's suggestion above) or do we want to breakdown the module + method stability as well?

I have a suggested solution which I will move into a PR soon.

My solution produces similar output to @shobhitchittora however it goes further to look for the Stability field for some APIs rather than just relying on a stability field always being present. It will always prefer the value in the stability first thou.

My question, however, is where would this script live in terms of a directory?

Here is an example on how the output would look like for the current latest version(node v12.2.0) :

|API|Stability|
| ---------------------- | ---------------- |
assert|(2) Stable
async_hooks|(1) Experimental
buffer|(2) Stable
child_process|(2) Stable
cluster|(2) Stable
console|(2) Stable
crypto|(2) Stable
dns|(2) Stable
domain|(0) Deprecated
Events|(2) Stable
fs|(2) Stable
http|(2) Stable
http/2|(2) Stable
https|(2) Stable
inspector|(1) Experimental
module|(2) Stable
net|(2) Stable
os|(2) Stable
path|(2) Stable
performance_timing_api|(1) Experimental
punycode|(0) Deprecated
querystring|(2) Stable
readline|(2) Stable
repl|(2) Stable
stream|(2) Stable
string_decoder|(2) Stable
timers|(2) Stable
tls_(ssl)|(2) Stable
trace_events|(1) Experimental
tty|(2) Stable
dgram|(2) Stable
url|(2) Stable
util|(2) Stable
v8|UNKNOWN
vm|(2) Stable
worker_threads|(1) Experimental
zlib|(2) Stable

[jhonatantft]

Hi, can I take this issue?

[davalapar]

Awesome, I think the right place would be here at https://nodejs.org/api/documentation.html#documentation_stability_index

[manisaiprasad]

If no one is working on it
I can give it a try.

[shobhitchittora]

@manisaiprasad You can give it a try.

[shobhitchittora]

@manisaiprasad You can give it a try.

[HassanRazaMuhammadTufail]

@shobhitchittora can I try this one?

[iammack]

Hey! First-time contributor here. Can I take this up if no one is working on it?
From what I understand from previous comments, @shobhitchittora has already created the tool to generate the table and all left is to insert this into the documentation?
Mentioning @jasnell here as he added the last label.

[joyeecheung]

Hi @iammack

I think the best way to move forward would be to try opening a PR with the suggestions above. Adding the script to tools/doc and make sure it's run from tools/doc/generate.js to insert the table into documentation.md whenever someone generates the doc would be a good first step.

[iammack]

I agree. I think that @shobhitchittora and @martin-dimitrov13 already have branches with their solutions. If neither of you is continuing with it, I can proceed.

[Lxxyx]

I'm working on this issue.