Bug Hunting Session
Bug 44502 - Improve Doxygen-generated SDK C++ documentation
Summary: Improve Doxygen-generated SDK C++ documentation
Status: RESOLVED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: LibreOffice (show other bugs)
Version:
(earliest affected)
Master old -3.6
Hardware: Other All
: medium normal
Assignee: Not Assigned
URL:
Whiteboard: target:5.4.0
Keywords: difficultyBeginner, easyHack, skillScript, topicCleanup
Depends on:
Blocks:
 
Reported: 2012-01-05 11:07 UTC by Stephan Bergmann
Modified: 2017-02-14 08:57 UTC (History)
7 users (show)

See Also:
Crash report or crash signature:


Attachments
ODK warning/build errors (46.49 KB, text/plain)
2012-06-15 08:22 UTC, Alex Thurgood
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Stephan Bergmann 2012-01-05 11:07:06 UTC
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.)
Comment 1 August Sodora 2012-01-19 10:21:00 UTC
Just for reference, how should we be running doxygen?
Comment 2 Stephan Bergmann 2012-01-19 11:51:22 UTC
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).
Comment 3 Alex Thurgood 2012-06-15 08:22:08 UTC
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.
Comment 4 Alex Thurgood 2012-06-15 08:24:04 UTC
(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
Comment 5 Stephan Bergmann 2012-06-18 01:28:02 UTC
(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.)
Comment 6 Alex Thurgood 2012-06-19 20:59:58 UTC
(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
Comment 7 Not Assigned 2012-08-05 22:25:31 UTC
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)
Comment 8 Michael Meeks 2013-06-11 15:18:21 UTC
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 :-)
Comment 9 Björn Michaelsen 2013-10-04 18:46:20 UTC
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
Comment 10 Robinson Tryon (qubit) 2015-12-14 06:56:38 UTC Comment hidden (obsolete)
Comment 11 Robinson Tryon (qubit) 2016-02-18 14:52:08 UTC Comment hidden (obsolete)
Comment 12 Arkadiy Illarionov 2017-01-29 11:10:34 UTC
(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?
Comment 13 Michael Stahl (CIB) 2017-01-30 21:42:26 UTC
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.
Comment 14 Commit Notification 2017-01-30 21:43:00 UTC
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.