[Libreoffice] Doxygen for C/C++ URE Documentation

[Stephan Bergmann]

Hi all,

<http://cgit.freedesktop.org/libreoffice/core/commit/?id=8907d159378b518a769e9f8c4f67290ec588a77d> 
"Temporary hack to work around autodoc bug" made it even more evident 
that our home-brewed autodoc is not up to its task and should be replaced.

So, I tried to switch to doxygen when generating the C/C++ header 
documentation in odk/pack/gendocu.  (There are apparently various 
alternatives to doxygen out there; I did not bother to look at any of 
them, given that doxygen is something of an "industry standard."  Speak 
up if you know of a superior alternative.)

And it worked quite well.  The parsed headers need some fixing (e.g., 
there's no @HTML command in doxygen, @tplparam is just @tparam, and 
@internal does something rather different and unfortunately needs to be 
replaced with more verbose @cond INTERNAL ... @endcond constructs), but 
overall it looks like the generated HTML pages are comparable in content 
to the existing <http://api.libreoffice.org/docs/cpp/ref/index.html>. 
Plus, the CPPUHELPER_DLLPUBLIC problem from the above commit is a 
non-issue with doxygen...  (One downside of doxygen appears to be that 
it does not generate an overview of all the non-class-member entities, 
like free functions; it only generates overviews of all the namespaces, 
classes, and files.)

If there are no objections, I will commit this to master later this week.

The build then has an additional dependency on the doxygen executable as 
a prerequisite.  This can be controlled via --with-doxygen, where an 
explicit --without-doxygen disables generation of the C/C++ 
documentation in odk (and --disable-odk skips the doxygen check 
completely in configure).  Tinderboxes that have no doxygen installed 
would need an explicit --without-doxygen to avoid configure failures. 
(Reportedly, doxygen works well on Mac OS X and Windows, but I did not 
check that.)

With autodoc no longer used to document C++, the next step would be to 
either replace its use to generate IDL docu as well (and completely 
remove autodoc), or at least remove the C++-specific autodoc code.  The 
SDK includes the autodoc executable, but I guess it would be OK to 
change that...

Stephan