On 2010-10-07 15:55-0700 Alan W. Irwin wrote: > The planned implementation will consist of an addition to the > scripts/style_source.sh script to deal with comment style using the > scripts/convert_comment.py python script to do the changes (in --diff > or --apply mode) rather than uncrustify (which as far as I know has > not implemented this style option yet). As with the rest of the style > changes that can potentially be applied by scripts/style_source.sh, > the --diff option gives you some safety (if you pay attention!) since > it gives you a preview of exactly what is going to be changed for > every file before you use the --apply option to actually make those > changes.
I have just done (revision 11257) the first chunk (essentially everything in src) of this commentary conversion project. That generated a ~27000-line context diff! Here are the steps I did including all the checks. I. A preliminary run of the script gave a runtime error because of one embedded comment, e.g., function( /* this is the first argument*/ x ) To my mind this is horrible comment style in any case (and I think everyone else agrees because there was only one instance). I therefore edited the file to get rid of the embedded comment and the check for this issue (anything after the trailing */ on a line generates a runtime error) will continue to be done by the script. N.B. This means new instances of embedded comments will generate script errors, but I doubt our contributors will generate many (if any) embedded comments so I haven't worried about implementing a more graceful way than a run-time error to deal with this case. II. Just out of curiosity I checked src for any non-blank characters in front of // before any changes were applied. softw...@raven> grep '[^ ]\+.*//' src/*.[ch] |less As expected the small number of instances (mostly URL's inside comments) were legit. III. While looking at the potential changes generated by the script (using "scripts/style_source.sh --diff -au |less") I checked inside the less command for the following two conditions: any trailing blanks; /. $ any insertions that don't have / anywhere on the line (a valid insertion should always have // on the line so if there is no / anywhere, that is an error); /^[+][^/]+$ These searches found nothing. IV. I also eyeballed all the potential changes in the ~27000-line context diff to look for any strange patterns in the resulting // comments. For various special reasons there were three instances of indentation errors for the comments that I spotted. (I have noted these issues and will fix by hand-editing later.) Other than these minor indentation issues I am completely satisfied with the style of the commentary now in src. convert_comment.py is fairly general and hopefully proof against most sorts of wacko styles of comments by our contributors. However, there are no guarantees so the best results will be derived from now on by not straining this script too much. N.B. For example, if you stick with //-style comments from now on, the script is guaranteed to not attempt to change anything in the files. V. The python script is specifically designed not to add or delete any lines to source files. I checked the number of lines in the files before and after the changes were applied to confirm this was the case. VI. After "scripts/style_source.sh --apply" was run, I found I had to run it a second time to take care of some minor realignment that uncrustify wanted to do because of the comment styling changes. But subsequent runs showed no further changes were generated. The reason for this good "non-recursive" result is I have logic in the python script to treat the case of "/***************..." correctly without generating spurious recursions. VII. I tested the new commentary style by running "cmake" and "make -j4 test_noninteractive" and "make -j4 test_interactive" in the build tree. No major build or run-time issues showed up as a result of those tests. Also, the visual results generated by "make -j4 test_interactive" looked good (within the general limitation of how fast they are displayed). N.B. Of course such test results are never complete so keep an eye out during this release cycle for any run-time bugs that may have been introduced by this change in commentary style. ToDo. Go through the same steps for other chunks of our C code. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ Beautiful is writing same markup. Internet Explorer 9 supports standards for HTML5, CSS3, SVG 1.1, ECMAScript5, and DOM L2 & L3. Spend less time writing and rewriting code and more time creating great experiences on the web. Be a part of the beta today. http://p.sf.net/sfu/beautyoftheweb _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
