Bug 44502

Summary:	Improve Doxygen-generated SDK C++ documentation
Product:	LibreOffice	Reporter:	Stephan Bergmann <sbergman>
Component:	Libreoffice	Assignee:	Not Assigned <libreoffice-bugs>
Status:	NEW ---	QA Contact:
Severity:	normal
Priority:	medium	CC:	augsod, dtardon, libreoffice, mst.fdo, m.weghorn
Version:	Master old -3.6
Hardware:	Other
OS:	All
Whiteboard:	EasyHack DifficultyBeginner TopicCleanup target:3.7.0
i915 platform:		i915 features:
Attachments:	ODK warning/build errors

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

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.