matthiasm wrote:
> On 16.03.2009, at 04:59, Greg Ercolano wrote:
>>
>> ________________ no variable names in prototype
>> / /
>> void insert (int, FL_BLINE *)
>> Insert a new line *t* before *line*.
>> \___________\____ variable names in docs
>
>
> Just add descriptive names. They need not be the same as in the source
> file (although it would be nice if they were).
Actually, we do kinda have to be sure they match:
doxygen appears to take the prototype from .H for the 'index',
and the function declaration in the .cxx for the 'detailed description'.
I'm quite sure of this; did several tests.
So if the names don't match, both varnames will be advertised, making
the docs look wrong either in the 'index' or 'full description'
if the \brief or first line of docs mentions them.
And nothing would really help us catch this:
> The compiler doesn't care if prototype varnames don't match
> Doxygen doesn't check this either; it only checks
\param[in/out]
against the .cxx function declaration names, not the .H names.
If the varnames are wrong in the prototype, it'll still be useful to
users descriptively at least, as long as the docs don't refer to the
names in the first line (or \brief), as that gets coupled in the index.
BTW, a concrete example; if the .H file prototype declares
"insert(aaa,bbb)"
and the source code function declaration declares "insert(line,t)",
doxygen and compiler won't complain, but you'll get this wrong result:
PROTECTED MEMBER FUNCTIONS
[..]
-------------------------------------------------------------------------
void insert (int aaa, FL_BLINE *bbb) <<<<< comes from .H
Insert a new line *t* before *line*. <-- DOCS DON'T MATCH ABOVE
-------------------------------------------------------------------------
[..]
DETAILED DESCRIPTION
_____________________________________________________________________
/ \
| void Fl_Browser::insert(int line, <<<<< comes from .cxx |
| FL_BLINE* t <<<<< comes from .cxx |
| ) [protected] |
|_______________________________________________________________________|
| |
| Insert a new line *t* before *line*. <-- DOCS MATCH OK |
| If line > size() then the line is added to the end. |
\_____________________________________________________________________/
_______________________________________________
fltk-dev mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-dev
