This might seem as an academic question, but when setting the version of our releases it’s important in order not to surprise our users. You might say that it is the public headers themselves, but that’s clearly not enough since they do not say very much about the semantics. Also, in that case they could per definition never be wrong.
I can think of several definitions:
- What’s documented. If so, which documentation? We have man pages, PDFs and the web pages.
- What’s de-facto been in the library for a very long time.
- What’s (apparently?) intended to be in the library or not.
The reason I’m asking is the new C++ API I’m working on. It’s going to be quite incomplete and probably change in a number of releases and I’m wondering if that’s a problem even if we do not document it until it’s complete? Or if we can document the parts that are implemented, but mark them as unstable or experimental in order not to warrant major releases when they change?
Any thoughts regarding this would be appreciated.