Duncan Gibson wrote:
> It my mind the problem here isn't long or short names, but consistency.
> Imagine that the declaration in the *.H has parameters with long names,
> but the definition in the *.cxx file has short or missing names, and you
> have to write the doxygen comments in the *.cxx file. It will confuse the
> next person to come along if you talk about \param windowtop, but the
> code you see right under it says 'p' ... a la Fl_Slider::scrollvalue()
Yep, good point.
So I take it during documentation fixing, if the prototype params
in the .H file don't match the .cxx and dox, then the .H file should
be modified to match the code/dox.
I'll keep that in mind if I encounter any of those.
Note: doxygen will warn us if \param[in] xxx is used in dox,
but doesn't match the parameters in the prototype.
So if we use \param[in], that will catch that kind of problem.
Of interest: "\p xxx" does NOT do checking.
Maybe \p should be avoided for that reason,
because it doesn't appear to do any consistency checks.
(Not sure why..)
_______________________________________________
fltk-dev mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-dev
