On Thu, 2009-05-21 at 22:35 -0500, Dean Glazeski wrote: > Hey Duane, > > Duane Ellis wrote: > > 1) Rather the commit this my self, I'd like somebody to read through > > the comments (double check my work), much of this is by just reading > > the source code and entering doxygen text. > This reminds me of what I've been doing ;). > > 2) Well call it "doxygen style", sure looks like doxygen, but it is > > not picking up the field documentation correctly. But hey, at least > > it's comments, a step in the right direction!. > It looks like the biggest issue is that some of those comment blocks are > not Doxygen blocks. They need to start with '/**' to be picked up. > Your patch brings up another question: Do we want documentation done > with \param (Doxygen "style") or @param (more like Javadoc). A lot of > the patches I have put through use the Javadoc style cause I use that at > work all the time in my Java career :). I would also suggest not > putting the function documentation on the same line as the '/**'. > Starting on the next line leads to a more boxed effect. > > I suppose this raises another question about what to do with > documentation standards along with coding standards. I have no major > preference though I think the Javadoc ones are easier to type (ah, my > Perl days) and looks a bit nicer. Plus, the @ style is used in phpdoc > too so it might be good to stick with a "standard". In the end, Doxygen > understands both, so its not a big issue. My 2 cents. Thanks for > providing docs.
Since no one has objected to my recently proposed style guide changes, I might take a shot at adding a section for this to my patch. Personally, I prefer (and have been using) '@' as well, partly because I think that character stands out visually better than '\' does. I also prefer a block-like style: /** * start commenting here */ But for one-line comments (of which this patch has a few), I prefer standard /** comment */; however, use /**< */ style comments after fields to minimize the number of added lines (if <80 columns total). Finally, be sure to read through your comments again. I see at least one sentence that seems to Cheers, Zach _______________________________________________ Openocd-development mailing list [email protected] https://lists.berlios.de/mailman/listinfo/openocd-development
