Matthias Melcher wrote: > > > Am 18.04.2009 22:53 Uhr schrieb "Albrecht Schlosser" ...
>> 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. Agreed, 100%. Simple variables that would otherwise look like text should be formatted with \c, the same as with function arguments. > Yes, I know. I used \c for code and \p for parameters. Sure, it is rendered > the same way. I have no problem with intermixing \p and \c, but maybe at some time in the future they might be rendered differently in doxygen. But IIRC they are documented to be equivalent, thus the probability of a change seems to be minimal. > I am fine with removing the extra \c again if you prefer that. I'm only concerned, where class names and method names are involved, because doxygen does already format them as links. If we start formatting them ourselves, then we must do it everywhere to be consistent. (And I don't like the \c look in this context, with links and maybe longer function names, but that's my personal opinion only). +1 for removing the extra \c before class names and method names, where doxygen formats them as links anyway. > 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. The above examples are all of this kind, where I'd prefer to remove the extra \c. > 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. Agreed. Maybe there's a way to change that with doxygen means or by changing the .css file(s)? > The \c in front of Fl_Group etc. is purely taste. I have no problem removing > that again. Yes, please, mainly for consistency. >> 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. Agreed. And, as mentioned somewhere else: It should read "Returns" and not "Return" (no imperative form). >>> - 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. I'm fine with \c here, but I share your opinion about the smaller display size. I adjusted my browser's font settings for fixed fonts, and now it looks somewhat better, but maybe this should be changed somehow... >>> 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. Absolutely. IMHO <tt> is okay for single code lines like here, but \code would be okay as well. >>> - 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. Here I used \e \b intentionally, because of the deficiencies of \c, but I'm okay with changing this to \p or \c (again, for consistent appearance in the docs). Albrecht _______________________________________________ fltk-dev mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-dev
