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
_______________________________________________
LibreOffice mailing list
LibreOffice@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/libreoffice
