Add "available since" message for C API additions since v1.10.0.

[edgchen1]

Description
Add "available since" message for C API additions since v1.10.0.

Motivation and Context
The C API docs may be updated with new APIs before they are available in a release. Adding a "new in version x" message indicates when they can be used.

#10298

[RyanUnderhill]

I don't think we want to say 'New in version 1.11' since that might sound weird after we're on 1.12.

Maybe even just \version 1.11 would be enough? I tried it locally and it looked clear and concise.

[natke]

Another idea is to adopt a word used in other code documentation systems: "since" e.g. javadoc (https://www.baeldung.com/javadoc-version-since)

It would become \since version 1.11

[RyanUnderhill]

What should we do when we remove APIs in the future? Looks like \since isn't setup to have an ending.

[edgchen1]

I suppose that text would have to go elsewhere, as the API being documented wouldn't be there anymore right?

[natke]

Do we ever remove APIs? ie how far back does our backwards compatibility commitment go?

[guoyu-wang]

Since we never remove functions from the c_api, could this be Available since version 1.11 or Since Version 1.11?

[RyanUnderhill]

Since we never remove functions from the c_api, could this be Available since version 1.11 or Since Version 1.11?

@gwang-msft We do plan on removing functions in the c_api, but only for newer versions of the API, not older ones.

[edgchen1]

@RyanUnderhill @gwang-msft
I got the wording from the Python docs: "New in version x", and if needed later, "Changed in version x"
For example: https://docs.python.org/3/library/os.html#os.environb

Not attached to a particular wording but we should be consistent.

[natke]

Another idea is to adopt a word used in other code documentation systems: "since" e.g. javadoc (https://www.baeldung.com/javadoc-version-since)

It would become \since version 1.11

[pranavsharma]

This looks like an additional burden for adding new APIs and can be easily forgotten. Would it be easier to have documentation based on the version?

[RyanUnderhill]

This looks like an additional burden for adding new APIs and can be easily forgotten. Would it be easier to have documentation based on the version?

@pranavsharma Since the issue was with stuff added to docs that were not in the latest release, perhaps we could have a temporary prerelease blurb instead? Something that explains "Checked into source but not in latest published release" that we then remove on release.

Easy to remove these on release vs try to find which ones we're missing on release. And this avoids having versions per function that might just be extra work.

[pranavsharma]

Ok, I guess we don't have an option now. It would be good to have docs versioned to begin with. Then there's just no confusion.

[edgchen1]

This looks like an additional burden for adding new APIs and can be easily forgotten. Would it be easier to have documentation based on the version?

Some examples with both versioned documentation and version-specific text within the documentation are CMake and Python.
https://cmake.org/cmake/help/v3.22/command/file.html#path-conversion
https://docs.python.org/3/library/os.html#os.environb

I think the version-specific text lets users more easily find something without having to go to the docs for their exact version. And given that we don't have versioned documentation, this is the only indicator.

[natke]

This looks like an additional burden for adding new APIs and can be easily forgotten. Would it be easier to have documentation based on the version?

I like being able to improve the documentation of any version out of band with the releases. If we generated the docs from a release branch of a particular version, then we are stuck with whatever docs annotations we had at the time of the release. We could continue to update the docs on the release branch, but then that would put the docs generation commit out of sync with the released commit. Also, if you do improve the docs of a particular release then do you cherry pick changes to all relevant versions? (I have done this in a past life and it was very onerous).

[natke]

@RyanUnderhill @gwang-msft I got the wording from the Python docs: "New in version x", and if needed later, "Changed in version x" For example: https://docs.python.org/3/library/os.html#os.environb

Not attached to a particular wording but we should be consistent.

Agree on the consistency. I like the convention in the Python docs that you have used.