Unix Power ToolsUnix Power ToolsSearch this book

21.4. Clean Up Program Comment Blocks

Lines in a program's comment block usually start with one or more special characters, like this:

# line 1 of the comment
# line 2 of the comment
# line 3 of the comment
    ...

It can be a hassle to add more text to one of the comment lines in a block, because the line can get too long, which requires you to fold that line onto the next line, which means you have to work around the leading comment character(s).

The fmt (Section 21.2) program neatens lines of a text file. But the standard fmt won't help you "neaten" blocks of comments in a program: it mixes the comment characters from the starts of lines with the words. (If your fmt has the -p option, it handles this problem; there's an example below.) The recomment script is fmt for comment blocks. It's for people who write shell, awk, C, or almost any other kind of program with comment blocks several lines long.

21.4.1. The recomment Script

Figure Go to http://examples.oreilly.com/upt3 for more information on: recomment

recomment reads the lines that you feed its standard input. It looks at the first line and figures out what characters you're using to comment the line (see the $cchars variable for a list -- typically SPACEs, TABs, #, or *). recomment then strips those comment characters off each line, feeds the remaining block of text to the fmt utility, and uses sed (Section 34.1) to add the comment characters again.

I usually use recomment from inside vi, with filter-through (Section 17.18) commands like:

!}recomment  reformat to the next blank line
5!!recomment reformat this line and the next 4

Normally, recomment lets fmt choose the width of the comment block (72 characters, typically). To get another width, you can do one of the following:

recomment isn't perfect, but it's usually much better than nothing! Here's the part of the script that does the work. The first two commands get the comment character(s) and count their length. The next three commands strip the comment characters, clean up the remaining comment text, and add the same comment characters to the start of all reformatted lines:

-n Section 34.3, expr Section 36.22, cut Section 21.14

# Get comment characters used on first line; store in $comment:
comment=`sed -n "1s/^\([$cchars]*\).*/\1/p" $temp`
# Count number of characters in comment character string:
cwidth=`expr "$comment" : '.*'`

# Re-format the comment block.  If $widopt set, use it:
cut -c`expr $cwidth + 1`- < $temp |     # Strip off comment leader
fmt $widopt |                           # Re-format the text, and
sed "s/^/$comment/"                     # put back comment characters

When the expr command in backquotes (Section 28.14) is expanded, it makes a command like cut -c4-.

21.4.2. fmt -p

Some versions of fmt (like the one on the CD-ROM [see http://examples.oreilly.com/upt3]) have a -p option that does the same thing. Unlike the automatic system in recomment, you have to tell fmt -p what the prefix characters are -- but then it will only reformat lines with that prefix character For example, here's the start of a C++ program. The prefix character is *:

% cat load.cc
/*
 * This file, load.cc, reads an input
 * data file.
 * Each input line is added to a new node
 * of type struct Node.
 */
    ...
% fmt -p '*' load.cc
/*
 * This file, load.cc, reads an input data file.  Each input line is
 * added to a new node of type struct Node.
 */
    ...

-- JP



Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.