add version provenance: (since [at least]) version x

[bob-carpenter]

Summary:

For the functions reference, add a provenance for each function indicating when it was introduced.

Description:

This is especially important now that the interfaces are releasing asynchronously and users often have later doc than the version of Stan they're using.

Additional Information:

It will be OK to follow the Python docs and allow "since at least".

It would also be nice to add the same thing for language features, but it's less clear where to document them. For example, the complex type was introduced recently, but types are described all over the doc.

There are lots of place this is listed: release notes, auto-generated function sigs, the actual stanc3 or previous stanc.

Current Version:

v2.28.0

[WardBrian]

So using extract_function_signatures.py I've generated a list of all the current function signatures alongside the first time they were able to be extracted. For 2.28 I used the commit before #394 to avoid all those changes being registered as adding new functions. Luckily, we haven't added any functions since that commit.

Here it is:
https://gist.github.com/WardBrian/74227d7062c4ecc8a9b6ff9d68cf5dde

This list is sorted by the order they appear in the .Rmd files. Getting this information back into the docs is non-trivial in effort, but definitely doable.

@rok-cesnovar - do you know of any other exceptions to the rule? skew_double_* do indeed appear as 2.27 on this list.

[rok-cesnovar]

Nice!

A few fixes for the gist:

• algebra_solver -> has been around since forever (I know at least earlier than 2.22)
• ode_* solvers are also not correct, these have been around for some time
• log_inv_logit_diff -> since 2.25
• log_modified_bessel_first_kind -> since 2.25
• ldexp -> since 2.25
• lambert_* -> since 2.25
• linspaced_array, linspaced_row_vector, linspaced_vector -> since 2.24
• linspaced_int_array -> since 2.26
• one_hot_, zeros_, uniform_simplex -> since 2.24

There may be other but I ran out of time today :)

We have only started enforcing adding docs before adding a function to stnac3 since a few versions ago, which is why there are a ton of functions where the docs was added late.

[WardBrian]

I think it’s fine to miss late, missing early is the problem. Saying something has been available since at least 2.23, when in reality it’s been in since forever, is probably okay as long as we don’t go in the other direction.

For things like the ODE solvers, changing signatures would count as “adding” new in my script, which I think is how we want it to be treated in general

[WardBrian]

Specifically, it seems like in 2.27 we marked algebra_solver as needing a data real array argument, not just a real array. How do we want to handle these?

I've updated the gist to reflect. See: https://gist.github.com/WardBrian/74227d7062c4ecc8a9b6ff9d68cf5dde/revisions

[rok-cesnovar]

This is just a fix, it always required data to compile to C++, stanc3 just did not enforce it until 2.27.

[WardBrian]

I considered trying to search through the old revisions of stan-dev/stan and find the functions from before 2.18, but it seems like the latex didn't have as consistent a format as the html does. So, until someone is much braver than me, 2.18 will be the furthest we can go back in history. Probably fine?

[bob-carpenter]

In the old LaTeX, we pulled the function sigs out of the index. But I think "since 2.18 (or before)" would be fine.

[WardBrian]

parsed the latex indices back to 2.0.0:
https://gist.github.com/WardBrian/74227d7062c4ecc8a9b6ff9d68cf5dde

Perhaps it is just the fallacy of round numbers, but it seemed best to go back that far rather than arbitrarily to 2.18.

I'll manually make @rok-cesnovar's edits as I add them to the doc. My plan is to say "Since at least" for all versions, but we could probably just say "Since" for versions after 2.0, and "at least" for only 2.0, if we wanted? The only false positives will be signature changes or renames, or flaws in documentation.

[bob-carpenter]

I'm OK with them all being "available since at least x.y.z" or "since x.yz or before". I worry the "least" gets confusing the same way as "turn up the air conditioner" is.

[WardBrian]

Does "First documented in version 2.5" sound okay or is that too specific to the way we're getting this information?

[bob-carpenter]

Now that I think about it, if we're going back to 2.0, I'd prefer to just say "available since x.y.z". We may miss some things that are available earlier, but I don't think that's a big deal.

P.S. The reason we can't just say "available since x.y.z" in general is that it implies that it wasn't available before that release due to scalar implicature (https://en.wikipedia.org/wiki/Scalar_implicature).

[bob-carpenter]

I like the plain old "Available since x.y.z" you finally went with!