On Mon, 2011-01-24 at 18:32 +0100, Soeren Moeller wrote: > Hi > > Thanks for pushing 0002 and 0004. > > In the doxygen documentation on > http://www.stack.nl/~dimitri/doxygen/docblocks.html in the section > "Putting documentation after members" I understand it as if the "<" is > necessary to tell doxygen that the comment relates to the statement > before (i.e. to the left of) the comment, instead of the statement > after (i.e. in the next line), so for instance: > > int foo; /**< counting foos */ > int bar; > > Here doxygen relates "counting foos" as a describtion of the variable > foo, while in > > int foo; /** counting foos */ > int bar; > > doxygen would understand "counting foo" as a describtion of the > variable bar, which would be wrong (same way for ///< resp. ///), did > I miss something?
Ah... So that tag is officially accepted by Doxygen. Fair enough. I personally wish they had not introduced extra tags for those same-line comments (since it's possible to detect them without extra tags). But they already made their decision and I'm sure they had their reasons & some use cases for them. > > I used ".\ " not for whitespace size but because it according to the > doxygen manual at http://www.stack.nl/~dimitri/doxygen/docblocks.html > avoids breaking the short description at the ".". Although this only > holds if we use doxygen with JAVADOC_AUTOBRIEF enabled, if not the > brief description should be given in another way. So which short > description type, do we use in Libre Office? Heh. No idea. ;-) I personally don't care that much about how the documentation is presented in detail, as long as it's presented. So, I'll defer the decision to someone who is more knowledgeable about doxygen. Thorsten? Miklos? Do you guys have any preference? Having said that, I personally hope that at least we should keep some readability of these documentations in the source code itself, because not everyone bothers to open the browser just to read the code doc. I for one prefer to read it just where the class is declared, in my own editor. This is why I'm a bit reluctant to see all whose text flow control markers that Doxygen apparently supports if that reduces the readability of the doc in the source code. But that's just personal preference. If we collectively decide to use all of those doxygen markers, then I'll learn to cope with it. > (Maybe we should figure > out and announce an offical convention how (and with which parameters) > to use doxygen in LibO and put it on the wiki.) Probably a good idea. It would be nice to have a page for that under the Development path if we don't have one already. But it will probably take some time for us to discuss, make decisions, and come to an agreement. So I've decided to push your other patches meanwhile. We can fix them afterward if we so decide. Thanks, Kohei -- Kohei Yoshida, LibreOffice hacker, Calc <kyosh...@novell.com> _______________________________________________ LibreOffice mailing list LibreOffice@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/libreoffice
