14.2.2 Formatting Comments

Comments in Ada code are of two kinds:

• a whole-line comment, which appears by itself (possibly preceded by “white space”) on a line
• an end-of-line comment, which follows some other Ada lexical element on the same line.

The indentation of a whole-line comment is that of either the preceding or following line in the formatted source, depending on switch settings as will be described below.

For an end-of-line comment, gnatpp leaves the same number of spaces between the end of the preceding Ada lexical element and the beginning of the comment as appear in the original source, unless either the comment has to be split to satisfy the line length limitation, or else the next line contains a whole line comment that is considered a continuation of this end-of-line comment (because it starts at the same position). In the latter two cases, the start of the end-of-line comment is moved right to the nearest multiple of the indentation level. This may result in a “line overflow” (the right-shifted comment extending beyond the maximum line length), in which case the comment is split as described below.

There is a difference between -c1 (GNAT-style comment line indentation) and -c2 (reference-manual comment line indentation). With reference-manual style, a whole-line comment is indented as if it were a declaration or statement at the same place (i.e., according to the indentation of the preceding line(s)). With GNAT style, a whole-line comment that is immediately followed by an if or case statement alternative, a record variant, or the reserved word begin, is indented based on the construct that follows it.

For example:

     

     if A then
         null;
            -- some comment
     else
        null;
     end if;
     

Reference-manual indentation produces:

     

     if A then
        null;
        --  some comment
     else
        null;
     end if;
     

while GNAT-style indentation produces:

     

     if A then
        null;
     --  some comment
     else
        null;
     end if;
     

The -c3 switch (GNAT style comment beginning) has the following effect:

• For each whole-line comment that does not end with two hyphens, gnatpp inserts spaces if necessary after the starting two hyphens to ensure that there are at least two spaces between these hyphens and the first non-blank character of the comment.

For an end-of-line comment, if in the original source the next line is a whole-line comment that starts at the same position as the end-of-line comment, then the whole-line comment (and all whole-line comments that follow it and that start at the same position) will start at this position in the output file.

That is, if in the original source we have:

     

     begin
     A := B + C;            --  B must be in the range Low1..High1
                            --  C must be in the range Low2..High2
                  --B+C will be in the range Low1+Low2..High1+High2
     X := X + 1;
     

Then in the formatted source we get

     

     begin
        A := B + C;            --  B must be in the range Low1..High1
                               --  C must be in the range Low2..High2
        --  B+C will be in the range Low1+Low2..High1+High2
        X := X + 1;
     

A comment that exceeds the line length limit will be split. Unless switch -c4 (reformat comment blocks) is set and the line belongs to a reformattable block, splitting the line generates a gnatpp warning. The -c4 switch specifies that whole-line comments may be reformatted in typical word processor style (that is, moving words between lines and putting as many words in a line as possible).

The -c5 switch specifies, that comments that has a special format (that is, a character that is neither a letter nor digit not white space nor line break immediately following the leading -- of the comment) should be without any change moved from the argument source into reformatted source. This switch allows to preserve comments that are used as a special marks in the code (e.g. SPARK annotation).