| Summary: | Improve Doxygen-generated SDK C++ documentation | ||
|---|---|---|---|
| Product: | LibreOffice | Reporter: | Stephan Bergmann <sberg.fun> |
| Component: | LibreOffice | Assignee: | Not Assigned <libreoffice-bugs> |
| Status: | RESOLVED FIXED | ||
| Severity: | normal | CC: | augsod, devel.marian.scerbak, dtardon, mentoring, michael.stahl, m.weghorn, robinson.libreoffice |
| Priority: | medium | Keywords: | difficultyBeginner, easyHack, skillScript, topicCleanup |
| Version: | Master old -3.6 | ||
| Hardware: | Other | ||
| OS: | All | ||
| Whiteboard: | target:5.4.0 | ||
| Crash report or crash signature: | Regression By: | ||
| Attachments: | ODK warning/build errors | ||
|
Description
Stephan Bergmann
2012-01-05 11:07:06 UTC
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. |