Am 18.04.2009 22:53 Uhr schrieb "Albrecht Schlosser" unter
<[email protected]>:
> I'm wondering, why you did the following changes (adding "\c") at
> places where doxygen does its own link highlighting.
>
> IMHO we should *not* add \c to links that are recognized by doxygen
> automatically. Otherwise we'd have to do this everywhere, and that's
> not the idea of using doxygen. (And personally I think that it looks
> worse than before).
OK, either way is fine with me. I did use \c to differentiate regular text
from code. So "set the value" and "set the variable \c value_" would be a
good example.
Yes, I know. I used \c for code and \p for parameters. Sure, it is rendered
the same way.
I am fine with removing the extra \c again if you prefer that.
Here is the reasoning for all your examples:
>> Modified: branches/branch-1.3/FL/Fl.H
>> ===================================================================
>> --- branches/branch-1.3/FL/Fl.H 2009-04-18 11:51:32 UTC (rev 6769)
>> +++ branches/branch-1.3/FL/Fl.H 2009-04-18 18:52:59 UTC (rev 6770)
>> @@ -852,29 +852,29 @@
>>
>> These functions support deletion of widgets inside callbacks.
>>
>> - Fl::delete_widget() should be called when deleting widgets
>> - or complete widget trees (Fl_Group, Fl_Window, ...) inside
>> + \c Fl::delete_widget() should be called when deleting widgets
>> + or complete widget trees (\c Fl_Group, \c Fl_Window, ...) inside
Fl::delete_widget() is valid C++ code, and since it is code, it should look
like code. But that truly is a question of taste. I am somewhat indifferent.
I agree that the choice of font size is bad in Doxygen and (at least on my
browser) code should not look smaller than regular text.
The \c in front of Fl_Group etc. is purely taste. I have no problem removing
that again.
>
> Most of the following changes are IMHO okay:
>
>> - returns a pointer to the watched widget.
>> + Returns a pointer to the watched widget.
The first sentence is used as the \brief description in Doxygen (AUTOBRIEF).
The full stop is required to tell Doxygen where the end of the brief
description is. And if there is a period at the end, the beginning of the
sentence should IMHO be capitalized.
>> - This pointer is NULL, if the widget has been deleted.
>> + This pointer is \c NULL, if the widget has been deleted.
Yeah, I am unsure about this myself. If it was "zero", I would not put a \c
in front of it. But again, in my browser, \c segments seem smaller in font
than regular text, which really annoys me.
>> This is a convenience method. You can also use something like
>>
>> - if (wp.widget() == 0) // ...
>> + <tt> if (wp.widget() == 0) // ...</tt>
It's code, so it should look like code. Maybe even a \code tag would be
needed here.
>> - where \e \b wp is an Fl_Widget_Tracker object.
>> + where \p wp is an \c Fl_Widget_Tracker object.
>
> Note: \p is equivalent to \c, so this should be:
Yes. This is only for my brain which identifies \p as *p*arameter and \c as
*c*ode. Other than that, no difference.
Matthias
_______________________________________________
fltk-dev mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-dev
