Mike (or someone), can you add me to svn?
Duncan, if you want, I can join the dox effort.
Maybe even fix a few simple bugs.
If you're still in the initial stages of working out the
dox style, I can hold off, or avoid certain parts you're
still working on. We can synchronize by email.
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
Also, probably wouldn't hurt to have two people on the
docs reading the dox manual. I know it'd make me put more
effort into absorbing it.
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..)
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, 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.
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:
----
// FIND ITEM THAT WAS CLICKED
const Fl_Tree_Item *find_clicked() const {
if ( ! _root ) return(0);
return(_root->find_clicked());
}
// SET ITEM THAT WAS CLICKED
void item_clicked(Fl_Tree_Item* val) {
_item_clicked = val;
}
----
..became this:
----
/// Find the item that was clicked.
/// You probably want to use item_clicked() instead, which is fast.
///
/// This method walks the entire tree looking for the first item that is
/// under the mouse (ie. at Fl::event_x()/Fl:event_y().
///
/// Use this method /only/ if you've subclassed Fl_Tree, and are receiving
/// events before Fl_Tree has been able to process and update
item_clicked().
///
/// \returns the item clicked, or 0 if no item was under the current event.
///
const Fl_Tree_Item *find_clicked() const {
if ( ! _root ) return(0);
return(_root->find_clicked());
}
/// Set the item that was last clicked.
/// Should only be used by subclasses needing to change this value.
/// Normally Fl_Tree manages this value.
///
void item_clicked(Fl_Tree_Item* val) {
_item_clicked = val;
}
----
Yuck.
I want to see if I can make a vim syntax script that allows
a function key to toggle "dimming out" dox comments, so one can
just see the raw source code and source comments without all
the noise.
Actually, it'd be really nice to be able to 'collapse' away
all the dox comments from within the editor, so that they're
not even shown at all, so they don't even have to be cursor'ed over.
Duncan Gibson wrote:
>> Duncan, I noticed you have not finished your hmtl doc modifications,
>> so I'll probably update the WWW (html+pdf) at the end of the week.
>
> I'm just fiddling about really, trying to get rid of the easier to
> fix STRs and bring the bug count down. I hadn't looked at the docs
> since before you did the big reorganization. I was waiting for the
> dust to settle and ran out of spare time to work. I had forgotten
> how much there is still to do on the documentation, removing html
> in favour of doxygen, etc. So I might end up fiddling for a while
> longer yet. I have a bit of spare time again...
>
> To be pragmatic, I would say that we don't need to update the
> 1.3.x html pages on the web for every minor typo correction. We
> should probably not aim for anything more regular than monthly.
> The fltk.pdf version can probably wait for three to six months,
> or the next release, whichever comes first.
_______________________________________________
fltk-dev mailing list
fltk-dev@easysw.com
http://lists.easysw.com/mailman/listinfo/fltk-dev
