Documentation: Should function documentation (etc.) include indication of what version the feature was added

[gwhitney]

And perhaps in addition, when the behavior changes, have some indication of which version the new behavior started? This could help if people are using a version different than what the current documentation is for (since unlike for some packages, there is no way to set the mathjs version in the documentation site to get the documentation for a specific version).

[josdejong]

Ah, yes, that would be good to have. I think we can extend the comment section of all functions which is used to generate the documentation can be used for this. I think it would be useful to list when the function was introduced but also in what versions there where breaking changes.

[gwhitney]

E.g., in addition to the current Syntax, Where, Examples, etc. sections, we have a History section? I will try to add support for this in my next PR.

[gwhitney]

This is implemented in #3375.

[gwhitney]

OK, I put an example implementation in #3375, but it was not germane to the main point of that PR and Jos deems it needs more discussion. So I will put here an overview of my approach to this:

(1) In some example functions (too many to do all in one pass, I assumed if this was approved we would gradually add them as
functions got added), I added to the documentation comments a section that looks like this one for the import function:

   * History:
   *
   *    v0.2  Created
   *    v0.7  Changed second parameter to an options object
   *    v2    Dropped support for direct import of a module by name
   *

(2) Then in tools/docgenerator.js I added a parseHistory function that collected up all of these lines, and in generateMarkdown in that file I added a block that laid out the lines in a table in the generated doc page. And that was it.

The idea is that whenever someone touched a function, they would add an entry for the change, or start up the History section if it was not already there, and over time we would have good coverage of function Histories. This seemed like epsilon work per PR that would gradually accumulate, and easy to check in review of PR that all History sections have been updated appropriately. Since the function source files were being touched anyway, it actually seemed easier than the current scheme of the reviewer needing to add a line to the central global HISTORY.md file.

Of course I am open to other schemes. I do think writing code to do a one-time mine of git commits to per-function History entries would be a difficult task, as git commit messages are pretty free-form and I don't know how to automate a check as to whether a given commit changed the behavior of a function or was just a behavior-preserving refactor (of which there are many in math.js's long history). The example History sections I made were generated by browsing/searching back-and-forth in the git blame for the relevant file, the git history, and the HISTORY.md. Even so, they are not necessarily 100% correct/complete, but I do think they are pretty good indications of what happened, and I think the most useful thing is to start collecting accurate information about changes going forward, which doesn't seem too difficult.

In fact, my strongest recommendation here is to start collecting the information deliberately in some form or other as the PRs are merged, even if it's not the final way that gets settled on, so that it doesn't just keep flowing under the bridge, so to speak.

[gwhitney]

Now that this scheduled for v16, three questions:

1. What changes, if any, are needed from thr prototype implementation that was in fix: Uniformize bigint construction #3375 ?
2. Is the goal to annotate all functions in v16, or just the majority that are touched for some other reason, leaving the others for whatever next future PR needs to modify them?
3. If the changes of a PR are entirely reflected in the per-function histories of the functions it touches, does it still also get an entry in HISTORY.md? (I think the answer is yes, just verifying.)

[josdejong]

1. I think what this new documentation feature includes is adding the history to each of the functions and adding support for it in the docgenerator, like was added in fix: Uniformize bigint construction #3375. Maybe the docgenerator can also give a warning when History is missing for a function.
2. Most neat would be to implement this for all functions. But that is quite some work (for each function, go though the HISTORY.md to find all relevant changes, and describe that in the function comment). If it's indeed much work, let's stay pragmatic and just do it for a subset for now (and from the docgenerator get information about the functions that still miss a History so we can add this over time).
3. Agree, we should keep HISTORY.md

[josdejong]

Implemented now via #3606. Closing this issue now.