Hello,
as a followup to the discussion during my talk at the LibreOffice conference,
I have created a wiki page describing how to use Doxygen to document code in
LibreOffice. A draft is at
https://wiki.documentfoundation.org/User:Llunak/Doxygen , if it's ok, I will
move it to Development/Doxygen and link from Development/ .
For those who weren't there (or try to pretend they don't remember :) ) : In
my talk I pointed out various problems that make it harder to develop
LibreOffice that it should be (taken mostly from experience, as I'm
relatively new to the codebase). One of the obvious problems is that a lot of
classes, functions, etc. are not documented at all or very poorly, which
causes a lot of problems, primarily that one has to spend a lot of time just
finding out how to actually use a class or even what the class is for, which
in turn means:
- developers cannot just look at a list of classes and see what they do,
because it's often not possible to instantly find out the purpose
- developers waste time finding out how to use a class instead of simply using
it
- or, they just do not use the class and duplicate the functionality, because
they either couldn't figure it out or didn't find it
- developers break design of classes by extending them in a way that does not
fit, because they do not know the exact purpose of the class (for example, we
have a class which can represent both a wall clock time and a duration)
Many of these could have been saved by somebody spending few minutes at most
and writting very short docs explaining this. Morever, whenever you "save"
time this way, it's usually wasted rather soon when you get back to the class
and need to spend even a little time to recall how to use it. As soon as
somebody else needs to use it too, they'll need even more time and so by not
spending that little time you actually waste much more time for the project
as a whole (had I somehow magically known everything about the code I've used
since I joined LO, in the time that I wasted trying to figure it out I could
have written very nice docs for all of it, still have quite some time left,
and that is only counting my time).
So, whenever you use a class or function that does not have any documentation
and you know or figure out the purpose, please spend a minute and write
something short. The same applies whenever you write something new of course.
Now that you know how, there's no real excuse.
--
Lubos Lunak
l.lunak@suse.cz
Context
- [Libreoffice] Using Doxygen for API documentation · Lubos Lunak
Privacy Policy |
Impressum (Legal Info) |
Copyright information: Unless otherwise specified, all text and images
on this website are licensed under the
Creative Commons Attribution-Share Alike 3.0 License.
This does not include the source code of LibreOffice, which is
licensed under the Mozilla Public License (
MPLv2).
"LibreOffice" and "The Document Foundation" are
registered trademarks of their corresponding registered owners or are
in actual use as trademarks in one or more countries. Their respective
logos and icons are also subject to international copyright laws. Use
thereof is explained in our
trademark policy.