[Libreoffice] Using Doxygen for API documentation

[Lubos Lunak]

 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 at suse.cz