[Libreoffice] [PATCH] [PUSHED, partial] Some comments and basic cleanup in sc
nthiebaud at gmail.com
Mon Jan 24 22:27:30 PST 2011
On Mon, Jan 24, 2011 at 1:24 PM, Kohei Yoshida <kyoshida at novell.com> wrote:
> On Mon, 2011-01-24 at 18:32 +0100, Soeren Moeller wrote:
>> 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 think that, kohei, you would probably prefer
int foo //!< counter of foos
Which is an accepted doxygen syntax.
> 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.
> Kohei Yoshida, LibreOffice hacker, Calc
> <kyoshida at novell.com>
> LibreOffice mailing list
> LibreOffice at lists.freedesktop.org
More information about the LibreOffice