> Regarding actual FLTK doc tweaking, I expect I'll only be > enhancing what's already in place.. I take it you all did the > heavy lifting of converting the old html over to dox.
I hope the others won't mind me saying this, but the initial conversion was very much a "let's add doxygen comment tags around the existing docs" effort. That meant that the bulk of the documentation became available in the doxygen generated html in a very short period. There are still a lot of things that need to be improved. As you have already noticed, there are a lot of places where there are comments that still hark back to the time when a single comment covered two or more forms of a function, or multiple functions that all appeared together. Now doxygen splits these functions apart, and the comment no longer makes complete sense. These comments usually say "the first form" and so on. These need to be teased apart. Where comments were transferred from a central rather than a class page, e.g. http://www.fltk.org/documentation.php/doc-1.1/drawing.html#drawing the multi-form comments need to be replaced in the central page with tagged paragraphs, where the tag gives the link to the class page. I have not explained it very well; it might make more sense if you check http://www.fltk.org/doc-1.3/index.html We also need to be careful that we don't duplicate text between the central and the class pages and we will probably need to revisit the central pages again in the future. Many of the comments still contain a lot of intrusive html format tags and corresponding layout. Although doxygen will honour [most of] them, it can do a better job if the doxygen forms are used. Several examples come to mind that render well, but are hard to read in the source. - We don't really need P tags to denote paragraphs any more and can simply use blank lines and more intelligent formatting of the text. - Many comments that contain lists are poorly laid out and obscured by UL and LI begin/end tags where \li and better formatting would work. - There are a lot of places (on the common pages) where things are highlighted between TT tags, but doxygen would show a link with emphasis if the correct text were used for the entry. Strictly speaking not a doxygem problem, but at the source level there are a lot of places where function/method signatures are not specified in a consistent way, with (int,int,int) for example, or with different parameter names in different places. We should address these too. So there is still a lot to do on the doxygen front, never mind bringing in the comments that have been added to the 1.1 docs on the web site, and other improvements. Cheers Duncan _______________________________________________ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
