> 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.
Right, I noticed that too for my own stuff, esp. with simple
set/get methods.
At first I tried using grouping.. this is supposed to work
according to doxygen chapter 5.2 on "Member Groups":
/*...@{*/
/** Sets/gets the sortorder, used for sorting the tree items. */
void sortorder(Fl_Tree_Sort val) { _sortorder = val; }
FL_Tree_Sort sortorder() const { return(_sortorder); }
/*...@}*/
But the result didn't look any different than commenting
the first and not the second; the methods were not grouped
together, and only the first method had a 'link'.
So I fell back to making separate comments for each,
ie. "Sets the sortorder." and "Gets the sort order.",
and felt I'd revisit later what the problem was.
But this made the docs really 'busy'; twice as large as
"the first form" approach. Especially annoying to read
when a class has lots of these.
> 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.
Yeah, I figured I wouldn't tackle that stuff; I figure the
lead person would set the precedent, and if its a big job,
we can each work on a piece by assigning sections out,
to prevent duplicate effort.
> 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.
Right. Blank lines definitely create paragraphs.. I actually
made a point to note that in the standards doc I started writing.
> - 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.
Yes, or even this seems to work well for lists:
- item one
- item two
- item three
- item four has multiple lines\n
that go on like this
- item five
For more, see Doxygen Chapter 4. It even supports nested lists,
and one can end a list with '.' I've used it, seems to work well.
It's the equiv of <li> in html; you get the same result.
> - 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.
Yes, that sounds good. dox seems to be good about just recognizing
keywords and assigning them links even when the word appears free-form.
> 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.
Yes, changing the code to use meaningful variable names.
This is going to be tricky/scary, esp. for single letter names;
very hard to search/replace.. have to be careful.
I think the reason for int,int,int,int might be to avoid
assigning variable names that are unused in the code, as these
would cause warnings from the compiler. SGI's compiler seems to
be pickier about this than linux.
> 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.
I think I'll just 'fix what I see' to start with.
I figure if there are known problems that you guys know about,
if it's too much to fix, you can assign me a section, and I'll
work on it.
Having a point person 'assign' the work is a good way to prevent
duplicate effort; I did this with taking all the old 1.1 buglist,
and breaking the giant result up into pieces that three or four of
us then took bites out of.
_______________________________________________
fltk-dev mailing list
fltk-dev@easysw.com
http://lists.easysw.com/mailman/listinfo/fltk-dev
