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

[Norbert Thiebaud]

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