Make API versioning compiler evaluable

[Jan-Marek Glogowski]

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...
-------------- next part --------------
A non-text attachment was scrubbed...
Name: since-grep-unique.log
Type: text/x-log
Size: 2164 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/libreoffice/attachments/20190411/a0b1a45b/attachment.bin>