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