Make API versioning compiler evaluable

Hi everyone,

while discussing https://gerrit.libreoffice.org/#/c/70528/, I realized that we
have actually extended API documentation using @deprecated and @since (which I
knew), but I don't know a way to automatically check them. Maybe I'm just
unaware, but I also couldn't find anything, neither via Web search nor various
greps on the code base.

Using opengrok I got "Searched full:deprecated" = 593 and "Searched full:"@
deprecated"" = 348. And while at it "Searched full:since" = 2959 and "Searched
full:"@ since" = 1447. So massive info is there :-)

IMHO we want to introduce something like glib/gversionmacros.h (see the end of
https://developer.gnome.org/glib/stable/glib-compiling.html). Nobody can
manually verify the use of deprecated or introduced functions with regard to the
version (@deprecated is sadly currently unversioned).

I was just aware of G_DISABLE_DEPRECATED, which glib / gtk has "since ever". Now
I found there also is (and we should use) GLIB_VERSION_MIN_REQUIRED and
GLIB_VERSION_MAX_ALLOWED. I was already bitten by not using this, when I checked
in the timer changes for the VCL gtk backend and found that our baseline glib
was too old, after pushing it.

Some questions that came to my mind:
* Has UDK an independent versioning, or is it also the Office version?
* Does anybody have a sensible idea to generate macros from docs or the other
way around?
* Is this easyhackable, if the required infrastructure is in place?
* Any good idea to automatically version the @deprecated?

More comments?

Jan-Marek

P.S. there are some funny @since, like "@since #i39203#". I've attached a "git
grep '@since' | sed 's/^[^@]*//' | sort -u". The 2007 dates are from
reportbuilder/java/org/libreoffice/report/pentaho/. The rest looks promising.
P.P.S. that would have been something for GSoC...

@overload @since LibreOffice 5.3 */
@overload @since LibreOffice 5.4 */
@since 02.03.2007
@since 05.03.2007
@since 06.03.2007
@since 07.03.2007
@since 08.03.2007
@since 09.03.2007
@since 0.9.2
@since 11.03.2007
@since 12.03.2007
@since 13.03.2007
@since 1.4
@since 14.03.2007
@since 15.03.2007
@since 1.7.0
@since 1.8.0.8
@since 19.03.2007
@since 20.03.2007
@since 22.03.2007
@since 24.03.2007
@since 26.03.2007
@since 30.03.2007
@since 31.03.2007
@since 3.5
@since 3.5.0
@since 4.5
@since AOO bug 75163 (OpenOffice.org 2.4.3 - OOH 680 milestone 212)
@since Apache OpenOffice 4.0, LibreOffice 4.2
@since \#i32109#
@since #i39203#
@since #i40086#
@since  LibreOffice 3.3
@since LibreOffice 3.3
@since LibreOffice 3.4
@since LibreOffice 3.5
@since LibreOffice 3.5.
@since LibreOffice 3.6
@since LibreOffice 4.0
@since LibreOffice 4.0 */
@since LibreOffice 4.1
@since LibreOffice 4.2
@since LibreOffice 4.3
@since LibreOffice 4.3 **/
@since LibreOffice 4.4
@since LibreOffice 5.0
@since LibreOffice 5.0 */
@since LibreOffice 5.1
@since LibreOffice 5.2
@since LibreOffice 5.3
@since LibreOffice 5.3 */
@since LibreOffice 5.4
@since LibreOffice 5.5
@since LibreOffice 6.0
@since LibreOffice 6.0 */ const short CHECKBOX_GPGENCRYPTION = 211;
@since LibreOffice 6.1
@since LibreOffice 6.1 */ const short LISTBOX_IMAGE_ANCHOR   = 212;
@since LibreOffice 6.1 */ const short LISTBOX_IMAGE_ANCHOR_LABEL = 213;
@since LibreOffice 6.1)</li>
@since LibreOffice 6.2
@since LibreOffice 6.3
@since OOo 1.1.2
@since OOo 2.0
@since OOo 2.0.0
@since  OOo 2.0.1
@since OOo 2.0.1
@since OOo 2.0.3
@since OOo 2.0.4
@since  OOo 2.1
@since OOo 2.1
@since OOo 2.2
@since OOo 2.3
@since OOo 2.3.1
@since  OOo 2.4
@since OOo 2.4
@since OOo 3.0
@since  OOo 3.0.1
@since OOo 3.0.1
@since OOo 3.1
@since OOo 3.2
@since OOo 3.3
@since OOo 3.4
@since OOo 3.5
@since pFilterOptions argument added in LibreOffice 5.0
@since       UDK1.0
@since UDK 1.0
@since UDK1.0
@since UDK2.0
@since UDK 3.1.0
@since UDK 3.2
@since UDK 3.2.0
@since UDK 3.2.1
@since UDK 3.2.10
@since UDK 3.2.12
@since UDK 3.2.13
@since UDK 3.2.2
@since UDK 3.2.3
@since UDK 3.2.7
@since UDK 3.2.8
@since UDK 3.2.9
@since UDK 3.6