Markup to describe when APIs were introduced/changed

[sam-github]

It would really help if the API documentation had some kind of consistent markup that described at what node version and API was introduced and or changed in a backwards incompatible way.

For example io.js newSession docs doesn't at all mention that the callback argument is new since 0.10.

Would this be a good place to report this?

The thing that is needed IMO is:

1. agreement that this is a problem and that inline text in the API docs is a solution
2. a markup template for what these notes should look like
3. ... people can PR into the API docs on an ongoing basis using the standard markup

[chrisdickinson]

1. agreement that this is a problem and that inline text in the API docs is a solution

IIRC, we reached agreement that noting introduction (and, when applicable, deprecation) versions is the desired course of action at Node summit last week.

1. a markup template for what these notes should look like

As a strawman:

* Introduced: vX.Y.Z
* Deprecated: v.X.Y.Z

We should also look into building an mdast plugin that can extract this info, linkify it to the appropriate section of the the CHANGELOG, and render it in a nicer form.

[wooorm]

As a side note, I’d love to help in any way possible regarding implementing mdast. As the author, I’m sure I can answer a lot of questions and implement feature requests fast!

[Qard]

In addition to the Introduced and Deprecated tags, it would also be good to have an Unstable tag to mark things that have been merged but are not yet available in stable. Similar to rust docs.

[Trott]

Closing as this repository is dormant and likely to be archived soon. If this is still an issue, feel free to open it as an issue on the main node repository.