The LibreOffice UNO SDK contains HTML documentation for the C/C++ entities that make up the interface of the UNO runtime environment (reached from the sdk/index.html starting page via the "C++ Reference" link). This documentation is now extracted from the relevant headers (modules sal, salhelper, cppu, cppuhelper, store, registry) with Doxygen. In the past, it used to be extracted with LO's own tool autodoc, which however had serious shortcomings. Most of the documentation syntax is the same for Doxygen and autodoc, but there are some differences, and Doxygen additionally warns for some things that autodoc silently ignored, like a misspelled "@param foo" that does not match any actual parameter name. Running doxygen at odk/pack/gendocu thus produces a large number of warnings. Some of them have been cleaned up with the initial commit <http://cgit.freedesktop.org/libreoffice/core/commit/?id=58ab12acf576a765ec47cc2753ba57643e51d653>, but lots still need to be addressed. Additionally, the documentation could need some general clean up, anyway (e.g., consistency in using full stops or not at end of documentation phrases, add missing documentation, use proper markup). Third, the "branding" of the generated HTML uses the default Doxygen settings and thus looks rather different from what the old, autodoc-generated HTML (still there at <http://api.libreoffice.org/docs/cpp/ref/index.html> as of today). The odk/pack/gendocu/Doxyfile could probably benefit from some more tweaking. (It is of course OK to only work on some part of this rather broad issue.)
Just for reference, how should we be running doxygen?
Doxygen is called in odk/pack/gendocu/ (". Env.Host.sh && cd odk/pack/gendocu && dmake", see odk/pack/gendocu/makefile.mk for how it is called exactly, or replace "dmake" with "VERBOSE=TRUE dmake" in the shell command to have dmake print out the doxygen command line -- together with many other things).
Created attachment 63078 [details] ODK warning/build errors Having built the ODK from master today, I am enclosing a text file containing the errors/warnings that doxygen generated.
(In reply to comment #3) > Created attachment 63078 [details] > ODK warning/build errors > > Having built the ODK from master today, I am enclosing a text file containing > the errors/warnings that doxygen generated. I will have a look at some of these and see if I can correct anything, but the "missing parameter" errors for some of the methods are beyond my reach - how is one supposed to find those out, other than by trial and error, if they aren't documented ? Alex
(In reply to comment #4) > I will have a look at some of these and see if I can correct anything, but the > "missing parameter" errors for some of the methods are beyond my reach - how is > one supposed to find those out, other than by trial and error, if they aren't > documented ? Not sure what you mean here. Do you mean warnings like /Users/Shared/LO/master/solver/unxmacxi.pro/inc/osl/socket.h:487: warning: The following parameters of osl_acceptConnectionOnSocket(oslSocket Socket, oslSocketAddr *pAddr) are not documented: parameter 'Socket' What needs to be done here is to add appropriate documentation for that parameter. (Which requires understanding of the function's semantics, so might or might not be adequate for an EasyHack.)
(In reply to comment #5) Hi Stephan, > What needs to be done here is to add appropriate documentation for that > parameter. (Which requires understanding of the function's semantics, so might > or might not be adequate for an EasyHack.) Yes, that is what I meant, and I understand your reply to mean that it is a job for someone who understands the programming language ;-) Not for me then, I'm afraid. Alex
Norah A. Abanumay committed a patch related to this issue. It has been pushed to "master": http://cgit.freedesktop.org/libreoffice/core/commit/?id=78b55ad11365bb97def308071bc45ca52cc557c7 Convert documents to follow the doxygen standard (fdo#44502, fdo#39468)
Michael - I wonder how we're looking with this bug after your work - it's on Joel's list of bugs with a patch that are not fixed :-)
adding LibreOffice developer list as CC to unresolved EasyHacks for better visibility. see e.g. http://nabble.documentfoundation.org/minutes-of-ESC-call-td4076214.html for details
Migrating Whiteboard tags to Keywords: (EasyHack DifficultyBeginner TopicCleanup) [NinjaEdit]
JanI is default CC for Easy Hacks (Add Jan; remove LibreOffice Dev List from CC) [NinjaEdit]
(In reply to Stephan Bergmann from comment #2) > Doxygen is called in odk/pack/gendocu/ (". Env.Host.sh && cd > odk/pack/gendocu && dmake", see odk/pack/gendocu/makefile.mk for how it is > called exactly, or replace "dmake" with "VERBOSE=TRUE dmake" in the shell > command to have dmake print out the doxygen command line -- together with > many other things). It seems that this instruction is outdated. I couldn't find odk/pack directory. What is current way of running doxygen?
the command to run doxygen is now make CustomTarget_odk/docs ... but it turns out there is only one warning left on current master that is easily located (there are a few where doxygen is so confused that it can't print a proper location, but that isn't an easy-hack but a doxygen bug), so this easy-hack is kind of obsolete now.
Michael Stahl committed a patch related to this issue. It has been pushed to "master": http://cgit.freedesktop.org/libreoffice/core/commit/?id=ca1cb1b4ac43be0e75f579fc38dadae37743617e tdf#44502 cppuhelper: fix doxygen warning It will be available in 5.4.0. The patch should be included in the daily builds available at http://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More information about daily builds can be found at: http://wiki.documentfoundation.org/Testing_Daily_Builds Affected users are encouraged to test the fix and report feedback.