indent formats both C and C++ comments. C comments are begun with
'/*', 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 between 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 necessarily in column 1).
indent further distinguishes between comments found outside of
procedures and aggregates, and those found within them. In
particular, comments beginning a line found within a procedure
will be indented to the column at which code is currently
indented. The exception to this is a comment beginning in the
leftmost column; such a comment is output at that column.
indent 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.
If the '-bbb' option is specified, all such boxed comments will
be preceded by a blank line, unless such a comment is preceded by
code.
Comments which are not boxed comments 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' 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 '-fnc' option is specified, all comments with '/*'
embedded will have that character sequence replaced by a space
followed by the character '*' thus eliminating nesting.
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
(unless the comment began in the first column). 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, unless they begin in
the first column, in which case they are left there by default
--- to get them aligned with the code, specify '-fc1'.
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. '-dj' together with '-cd0' can be
used to suppress alignment of comments to the right of
declarations, causing the comment to follow one tabstop from the
end of the declaration. Normally '-cd0' causes '-c' to become
effective.
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, unless the '-ntac' option is
specified. In the case of preprocessor directives,comments are
extended to 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 /* Loving hug */ can be
transformed into:
/*
Loving hug
*/
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:
/*
* Loving hug
*/
