indent formats both C and C++ comments. C comments are begun with
`/*' and terminated with `*/' and may contain newline
characters. C++ comments begin with the delimiter `//' and end at
the newline.
indent handles comments differently depending upon their context.
indent attempts to distinguish amongst comments which follow
statements, comments which follow declarations, comments following
preprocessor directives, and comments which are not preceded by code of
any sort, i.e., they begin the text of the line (although not
neccessarily in column 1).
indent further attempts to leave boxed comments
unmodified. The general idea of such a comment is that it is enclosed
in a rectangle or "box" of stars or dashes to visually set it apart.
More precisely, boxed comments are defined as those in which the initial
`/*' is followed immediately by the character `*', `=',
`_', or `-', or those in which the beginning comment delimiter
(`/*') is on a line by itself, and the following line begins with a
`*' in the same column as the star of the opening delimiter.
Examples of boxed comments are:
/**********************
* Comment in a box!! *
**********************/
/*
* A different kind of scent,
* for a different kind of comment.
*/
indent attempts to leave boxed comments exactly as they are found
in the source file. Thus the indentation of the comment is unchanged,
and its length is not checked in any way. The only alteration made is
that an embedded tab character may be converted into the appropriate
number of spaces.
Comments which are not boxed may be formatted, which means that the line is broken to fit within a right margin and left-filled with whitespace. Single newlines are equivalent to a space, but blank lines (two or more newlines in a row) are taken to mean a paragraph break. Formatting of comments which begin after the first column is enabled with the `-fca' option. To format those beginning in column one, specify `-fc1'. Such formatting is disabled by default.
The right margin for formatting defaults to 78, but may be changed with the `-lc' or the `-l' option. `-l' specifies the right margin for all code, and `-lc' specifies the margin for only for comments. If `-l' is used alone, comments will be formatted according to the margin specified with that option.
If the margin specified does not allow the comment to be printed, the margin will be automatically extended for the duration of that comment. The margin is not respected if the comment is not being formatted.
If the comment begins a line (i.e., there is no program text to its left), it will be indented to the column it was found in unless the comment is within a block of code. In that case, such a comment will be aligned with the indented code of that block. This alignment may be affected by the `-d' option, which specifies an amount by which such comments are moved to the left, or unindented. For example, `-d2' places comments two spaces to the left of code. By default, comments are aligned with code.
Comments to the right of code will appear by default in column 33.
This may be changed with one of three options. `-c' will specify
the column for comments following code, `-cd' specifies the
column for comments following declarations, and `-cp' specifies
the column for comments following preprocessor directives #else
and #endif.
If the code to the left of the comment exceeds the beginning column, the comment column will be extended to the next tabstop column past the end of the code, or in the case of preprocessor directives, to one space past the end of the directive. This extension lasts only for the output of that particular comment.
The `-cdb' option places the comment delimiters on blank lines.
Thus, a single line comment like /* Claustrophobia */ can be
transformed into:
/* Claustrophobia */
Stars can be placed at the beginning of multi-line comments with the `-sc' option. Thus, the single-line comment above can be transformed (with `-cdb -sc') into:
/* * Claustrophobia */
Go to the first, previous, next, last section, table of contents.