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

[Kohei Yoshida]

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
<kyoshida at novell.com>