Date: prev next · Thread: first prev next last
2011 Archives by date, by thread · List index


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@novell.com>


Context


Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0 License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License (MPLv2). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.