Re: [Libreoffice] [PATCH] [PUSHED, partial] Some comments and basic cleanup in sc

On Mon, Jan 24, 2011 at 1:24 PM, Kohei Yoshida <kyoshida@novell.com> wrote:
> 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 think that, kohei, you would probably prefer
int foo  //!< counter of foos

Which is an accepted doxygen syntax.

Norbert

> 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
> <kyoshida@novell.com>
>
> _______________________________________________
> LibreOffice mailing list
> LibreOffice@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/libreoffice