Skip to content

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

Closed
Closed
Show "supported since version x" for functions in API documentation#3713
Labels
docIssues and PRs related to Node.js documentation.

Description

@watson
watson
opened on Nov 8, 2015

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.

Activity

  1. Fishrock123
    added
    docIssues and PRs related to Node.js documentation.
    on Nov 8, 2015
  2. ChALkeR
    added
    feature requestIssues requesting new Node.js features.
    and removed
    feature requestIssues requesting new Node.js features.
    on Nov 8, 2015

  3. evanlucas commented on Nov 9, 2015

    @evanlucas
    evanlucas
    on Nov 9, 2015
    Contributor

    FWIW I think this is a great idea

  4. Qard commented on Nov 9, 2015

    @Qard
    Qard
    on Nov 9, 2015
    Member

    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! 😄

  5. watson commented on Nov 9, 2015

    @watson
    watson
    on Nov 9, 2015
    MemberAuthor

    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:

    screen shot 2015-11-09 at 10 19 46

    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.

  6. targos commented on Nov 9, 2015

    @targos
    targos
    on Nov 9, 2015
    Member

    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.

  7. r-52 commented on Nov 9, 2015

    @r-52
    r-52
    on Nov 9, 2015
    Contributor

    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)

  8. watson commented on Nov 9, 2015

    @watson
    watson
    on Nov 9, 2015
    MemberAuthor

    @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?

  9. jwueller commented on Nov 12, 2015

    @jwueller
    jwueller
    on Nov 12, 2015
    Contributor

    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.

  10. tflanagan commented on Nov 13, 2015

    @tflanagan
    tflanagan
    on Nov 13, 2015
    Contributor

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

  11. jwueller commented on Nov 13, 2015

    @jwueller
    jwueller
    on Nov 13, 2015
    Contributor

    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 [...]

  12. watson commented on Nov 13, 2015

    @watson
    watson
    on Nov 13, 2015
    MemberAuthor

    @jwueller looks good!

    @tflanagan what does the generate.js tool do?

  13. Fishrock123 commented on Nov 13, 2015

    @Fishrock123
    Fishrock123
    on Nov 13, 2015
    Contributor

    @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. :)

  14. watson commented on Nov 13, 2015

    @watson
    watson
    on Nov 13, 2015
    MemberAuthor

    @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?

  15. 10 remaining items

  16. evanlucas
    added a commit that references this issue on May 17, 2016

    tools: parse documentation metadata

    cea1777

  17. evanlucas commented on May 24, 2016

    @evanlucas
    evanlucas
    on May 24, 2016
    Contributor

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

  18. evanlucas
    closed this as completedon May 24, 2016
  19. MylesBorins
    added 3 commits that reference this issue on Jul 12, 2016

    tools: parse documentation metadata

    f49158a

    tools: parse documentation metadata

    f0f990a

    tools: parse documentation metadata

    2832a60
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docIssues and PRs related to Node.js documentation.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions