> 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.
You give me too much credit. Matt started, but Fabien did almost all of the work in getting the doxygen framwork in place, and he and Albrecht did the bulk of the initial document conversion. > 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. There is a sort of style guide, in the Developer Information appendix. > 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. That would be useful. The comments obviously reflect what people found difficult, or thought could be improved. > Maybe even add a few small small 2-to-4 line \code examples > that would help users, as some widgets really need it, Agreed. > 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. Some of the existing docs only really make sense if you know what the code already does, because the choice of short parameter names can obfuscate if you come from the outside, eg scrollvalue(p,W,t,l) > 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. [...] The initial conversion to doxygen was an amazing achievement because it was a lot of work in a short time, but there is still scope for improvement. A lot of the intrusive html tags and /tags could still be replaced by the less intrusive doxygen \command style. That's what I was hoping to do as a background task, file by file. There was too much going on at the beginning to do that without trashing someone else's hard work. > Would also like to include screenshots of widgets, so that each > widget [has] a small screenshot showing what it looks like. Agreed, although these would have to be kept up to date manually. > 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. Agreed. I think this is particularly noticeable in header files where the code is particularly terse and very compact. But, I also think that having all of these function signatures with single letter or missing parameter names is actually something that we should improve over time anyway. And we should aim for consistent naming too, not like the scrollvalue case which I have seen with (p,W,t,l), (p,s,top,total) and (windowtop, windowsize, first, length) or something like that. If there was a more literate naming style, we wouldn't need the same level of doxygen comments. Cheers D _______________________________________________ fltk-dev mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-dev
