Show "supported since version x" for functions in API documentation

[watson]

I think it would be useful to show from which version a given function in the API is supported, e.g. Buffer.prototype.indexOf() was added in v4.x, so if I'm creating a node module that should be backwards compatible with node v0.12, I shouldn't use that function.

I'll happily make pull request with this change - and please comment if you have deeper knowlege of the documentation system in case there are ways to (semi-)automate this in some way.

[evanlucas]

FWIW I think this is a great idea

[Qard]

The docs wg has already discussed this idea before and we seemed to all agree it is a thing we want. We just haven't got to it yet. Contributions in that regard are absolutely welcome! 😄

[watson]

There are tons of ways to visually display this. I just messed around with the dev tools and mocked this up to get the discussion going:

Any other suggestions?

As reference, the PHP docs have something similar - notice the (PHP 4, PHP 5) at the top of this page: http://php.net/manual/en/function.setcookie.php

Also, maybe we should consider supporting the few cases where the API for a given function have changed between two versions of node - e.g. fs.readFile changed it's 2nd argument from a string to a an object at v0.9.11.

[targos]

I think we need to be more precise about the version number. Because we are following semver, a method could be added in v5.4.

[r-52]

Maybe it makes sense to also include a short notice about the first (soft) deprecation of a module/ function.
Right now the docs mention that it's deprecated, but not when the function was first deprecated (or even when it's expected to be removed)

[watson]

@targos good point 👍

@romankl does it matter from which version a function is deprecated and do we know up front in which version that function is expected to be removed?

[jwueller]

This is a great idea, I've actually had to figure it out manually several times in the past. Not fun.

@watson's mockup looks great and keeping version numbers as precise as possible is definitely the right thing to do.

Concerning deprecation versions: I do not think those are relevant information, since no functionality actually changes in those cases.

[tflanagan]

How would this look in the markdown? Can get started on the generate.js tool once this has consensus.

[jwueller]

I would propose to just use something like <sup/>, potentially combined with an emphasis. Markdown does not have superscript, and we need some kind of unique-ish thing that does not interfere with any function signatures. Something like only emphasizing would probably work as well, but I feel that superscript is harder to misinterpret as part of the signature.

### buf.indexOf(value[, byteOffset]) _<sup>since v5.4</sup>_

* `value` String, Buffer or Number
* `byteOffset` Number, Optional, Default: 0
* Return: Number

Operates similar to [...]

---

buf.indexOf(value[, byteOffset]) ^{since v5.4}

• value String, Buffer or Number
• byteOffset Number, Optional, Default: 0
• Return: Number

Operates similar to [...]

[watson]

@jwueller looks good!

@tflanagan what does the generate.js tool do?

[Fishrock123]

@watson generate.js is our current doc generation tool. It turn markdown into html mostly.

Note that it's pretty fragile and hasn't been touched in years. :)

[watson]

@Fishrock123 thanks for explaining 😃

So if I understand it correctly, the process would have to look something like this(?):

1. The generate.js tool needs to be updated to understand the new syntax
2. Someone needs to add _<sup>since vx.y</sup>_ where appropriate throughout the docs

I don't mind making a PR with no 2 if we agree on the markdown format.

@jwueller In my example I added the css style font-weight: normal to ensure a bigger contrast between it and the function headline. But I guess we can tweak all that stuff in css later? Or do we need to add something special in the markdown for it to work?

[tflanagan]

Yea, I was going to couple this change with the fix for #1545 (not the same commit, just same "work session")

@watson That's a "Go for no. 2" ;)

I'll work on no. 1 when the consensus is made.

[jwueller]

@watson If we were only ever using a generator script that compiles to HTML, there would be no need to do more than a single element (like <sup/>). It's just some element to add the CSS to.

However, I would ideally like to have this be readable in non-generate.js scenarios as well (e.g. the GitHub Markdown renderer). That is why I proposed emphasis in addition to <sup/>. We have free choice of styles in the generate.js scenario, but the options are limited for standard Markdown viewers. <sup/> plus emphasis seems to be a good compromise between markup complexity and readability in the final non-generate.js output.

[tflanagan]

Just as a side note, @jwueller, GitHub markdown does support the ^superscript tag.

[watson]

@jwueller yeah, it would be really nice if the markdown files are readable on GitHub as well. But I'm ok with the "since"-text being bold on GitHub. Most people are going to look at the docs on nodejs.org, so as long as we can tweak the the CSS there I think we're good 😃

[jwueller]

@tflanagan Is there any special markup for it? I cannot seem to find anything. My original example used the <sup/> HTML tag, since Markdown permits custom HTML.

@watson The emphasis in my example was only added to improve readability on GitHub. There is no way that I am aware of to un-bold text using Markdown syntax alone, so that is how it'll have to be. The CSS for the documentation pages can obviously improve this even more.

[tflanagan]

@jwueller, I've finished modifying the generation tool. See #3867.

[jmm]

+1 for this. People love to knock PHP, but its documentation has done a better job of communicating this information than any similar documentation I can think of.

@targos @watson mentioned that they display some broad version information at the top of each page (it's not always just the major version number), but (as applicable) pages also include a Changelog section that logs changes down to patch level and includes things like changes to function signatures.

Example:

Top of page:

(PHP 5 >= 5.2.0, PECL json >= 1.2.0, PHP 7)

Changelog:

Version	Description
5.6.6	JSON_PRESERVE_ZERO_FRACTION option was added.
5.5.0	depth parameter was added.
5.4.0	JSON_PRETTY_PRINT, JSON_UNESCAPED_SLASHES, and JSON_UNESCAPED_UNICODE options were added.
5.3.3	JSON_NUMERIC_CHECK option was added.
5.3.0	The options parameter was added.

[kzc]

@jmm +1. Tracking changes to function arguments across node releases would have been very useful to me for #4317

[evanlucas]

Closing in favor of #6578. That issue is a duplicate of this. There is great progress being made on this front. Thanks!