Greg, your efforts would be welcome!
I won't comment on things that others commented, but some points...
Greg Ercolano wrote:
> I'd like to help address some long standing doc omissions,
> go through the old 1.1.x "User Comments" and try to bring in
> any obvious stuff from those.
>
> Maybe even add a few small small 2-to-4 line \code examples
> that would help users, as some widgets really need it, eg.
>
> Here's an example of how to walk the entire Fl_Browser's array.
> Note Fl_Browser's index numbers are 1 based..!
> \code
> for ( int t=1; t<=browser->size(); t++ ) {
> printf("item #%d, label='%s'\n", t, browser->text(t));
> }
> \endcode
Good example. There are still lots of old comments, some of the
form "the first version" and "the second version" (IIRC Duncan fixed
one of those recently, STR #(don't know)).
From Fl_Browser::text:
"const char * text (int) const
Returns data entry for line line, or NULL if out of range.
void text (int, const char *)
Sets the text for line line to text newtext."
As Duncan mentioned elsewhere, the argument lists in the old
docs are often without variable names, e.g. there is no argument
called "line" in the argument list, but it is referenced in the
comments.
There are also some methods that would need the units of the
arguments (e.g. is it pixels or lines ?)
> I'd also be happy to start or assist in the creation of an
> FLTK doxygen "standards" page that describes how docs should
> appear, so that new docs follow a certain format.
>
> Such a document should probably describe the rational behind
> whether to put dox in .H or .cxx files.. (my guess is they
> should be near the implementation, ie. if a method is implemented
> in the .H then dox should be there, if in the .cxx, dox go there..)
Yes, that's what we decided once.
I started appendix "I - Developer Information" when we started the
doxygen comments just for documenting how the docs should be made,
but I got stuck :-(
Currently it is just a lot of unsorted material that needs management
and improvement... If you'd like to do that, I'd appreciate it (IMHO
it's always good if a native English speaker writes longer text docs).
> Would also like to include screenshots of widgets, so that each
> widget ends up having a small screenshot showing what it looks like.
> eg. Fl_Value_Input has a small screenshot:
> http://fltk.org/doc-1.3/classFl__Value__Input.html#_details
>
> All the widgets should probably have one of those at the head
> of their descriptions,
Agreed, maybe with some exceptions where obvious...
> and maybe even a gallery of these same
> images, so one can easily browse for the widget they're looking
> for, and then click that widget to see the docs for it.
Don't know ...
> I'm sure we have to watch that the dox don't get too crazy,
> as we don't want it to eclipse the source code with noise.
> It's a delicate balance.. maybe someone can shed some light
> on what techniques are best. I know I shed a tear when I
> started doxifying my tree widget.. was real happy with how
> nice and terse the code was, but the dox mixed in really
> lost that terse look. For instance, this:
[... example snipped ...]
Personally I don't have problems with comments in the sources. Sometimes
I'd like much more comments in the code (not only doxygen, but also
some hints what the code is good for).
Albrecht
_______________________________________________
fltk-dev mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-dev
