Comments

Comments

• Section Automatically Inserted Comments
• Section User Comments

• Section Header Comments

Automatically Inserted Comments

• In-line diagnostic messages,
• Inter-unit pagination comments, and
• Echoed unit, block, and loop names.

In-Line Diagnostic Messages

Ada-ASSURED maintains certain diagnostics incrementally during editing. Unlike a batch analysis tool that must be invoked periodically to update diagnostic output, Ada-ASSURED updates these messages immediately as the program is edited. Each message is formatted as a comment that begins with a distinctive prefix:

--ERROR-- [Enum] <text>	Ada language error
--VIOLATION-- [Vnum] <text>	Style enforcement violation
--INDICATOR-- [Inum] <text>	Style enforcement indicator

X := 2#0001_0002#
       --ERROR-- [E21] All digits in the mantissa must be less than
       --ERROR-- the base.
       ;
Y := not (A or not (B and not C)) or C
       --VIOLATION-- [V19] Number of negative logic occurrences of
       --VIOLATION-- 3 exceeds maximum of 2.
       ;
Z := P / (Q / (R / (S / (T / (U / (V / W))))))
       --INDICATOR-- [I2] Expression nesting depth of 6 exceeds
       --INDICATOR-- maximum of 5.
       ;

• Display Errors

• Display Violations

• Display Indicators

• Inline displays the messages within the text of your Ada code,

• MESSAGES displays the messages in the MESSAGES view,

• Both displays the messages both inline and in the MESSAGES view, and

• No suppresses the display of all such messages.

A complete list of all diagnostic messages together with their interpretation appears in Section Messages.

Inter-Unit Pagination

An inter-unit ``pagination comment'', as recommended by the SPC style guide, can be automatically inserted around packages, tasks, procedures, and functions. For example,

--~----------------------------------
package body P is
    --~-------------------------------
    procedure F is
    begin -- F
       <statement>
    end F;
    --~-------------------------------
end P;
--~----------------------------------

Comments that are contiguous with the beginning of the item are included within the pagination markers.

Name Echoing

User Comments

Ada-ASSURED supports several sorts of user comments described below. The different kinds of comments are identified by the first character after --. The choice of characters can be customized using Ada-ASSURED resources and enforcement parameters. The default choices are:

--	normal comment
--+	continuation comment
--|	untouchable comment
--(	begin freeform region
--)	end freeform region
--C	commented out code
None	message comment

Left Comments and Right Comments

-- This is a left comment.
-- This is another left comment.

-- Step One.
if X = 0 then
    -- swap A and B.
    T := A;
    A := B;
    B := T;
end if;

X := 0;       -- This is a right comment.
Y := Z + 1;   -- This is another right comment.

Continuation Comments

-- This is a long comment that has been split
-- into two comments so no line is too long.
Put("Hello World");

...
    begin
          -- This is a long comment that has
          --+ been split
          -- into two comments so no line is
          --+ too long.
          Put("Hello World");
    end
...

The above example illustrates that each comment is wrapped individually. This is similar to the wrapping of text in a word processor where each paragraph is wrapped individually. Without knowing whether successive comments are related, this is as good a job as we can do. However, suppose the second line of the original commentary had been entered as a continuation comment:

-- This is a long comment that has been split
--+ into two comments so no line is too long.
Put("Hello World");

...
    begin
          -- This is a long comment that has
          --+ been split into two comments
          --+ so no line is too long.
          Put("Hello World");
    end
...

• If the comment is unfinished when you reach the right end of the window,

  • strike LineFeed or Control+J, which advances to the next line without invoking parsing,

  • type --+, which signifies a continuation comment,

  • type the rest of the comment using the same procedure, if necessary, at the end of the line.

Old code that has been manually formatted may contain comments that are not indented according to the structure of the Ada. For example,

if B then
---------------------------------------
-- This is the really important case --
---------------------------------------
    X := 0;
end if;

• horizontal box edges that cannot be broken because they contain no blanks may exceed the maximum line length after being indented, and

• vertical box edges and tabular information are scrambled when wrapped.

if B then
    ---------------------------------------
    -- This is the really important
       --+ case --
    ---------------------------------------
    X := 0;
end if;

• Untouchable comments,

• Column-one comments, and

• Freeform text.

• it remains in the same column as in the input file,

• it can be edited to begin in an arbitrary column, and

• it is never word wrapped.

if B then
--|-----------------------------------
--| This is the really important case
--|-----------------------------------
    X := 0;
end if;

Column-One Comments

If Ada-ASSURED resource columnOneComments is True (see Setting Resources), all comments that begin in column one are treated specially. In particular:

• all comments that begin in column one of the input remain in column one regardless of their contexts, and

• such comments are never word wrapped.

Freeform text

Certain regions of text can be marked as freeform. Within these regions, any text may appear, even illegal Ada code. This can be used to exempt regions of code from processing by the formatter.

The region of freeform text is bracketed by distinctive comments, e.g., --( and --), that must each appear on their own lines. For example:

--(
    A := 0; B := 0; C := 0;
--)

The Ada-ASSURED resource parseFreeformText controls whether an attempt should be made to parse the freeform text. If it is True, the text will be parsed, and if there is a syntax error, an error message will be printed before the text. For example:

--ERROR-- Freeform text contains syntax error.
--(
    this is freeform text
--)

The enforcement parameter Freeform Text Enforcement controls whether an occurrence of freeform text should be considered to be a violation. If on, the following message will appear for each occurrence of freeform text:

--VIOLATION-- Freeform text is not allowed.

Message Comments

One use for message comments is to annotate the style diagnostic report with explanations or excuses. For example, suppose a particular use of goto is authorized, but goto statements, in general, are considered violations. Then a message comment can be used to record the authorization. For example, suppose violations are displayed in the MESSAGES view, but not inline. Then the Ada file segment

--M Style waiver W13457. Authorized by John Doe, 4/1/94.
goto L;

--M Style waiver W13457. Authorized by John Doe, 4/1/94.
--VIOLATION-- Use of GOTO is not allowed.

A second use for message comments is bookmarks. As with any line in the MESSAGES view, clicking on a bookmark scrolls to the corresponding location in the Ada code. Bookmarks placed (temporarily) at the locations of current interest facilitate rapid context switches among those locations.

Commented-out Code

A := 0; 
-- On platform 007, initialize as follows: 
--C A := 2#0001_0002#
--C       --ERROR-- [E21] All digits in the mantissa 
--C       --ERROR--   must be less than the base.
--C       ;
B := 0;

One use for such comments is for an Ada-based design. The Ada constructs are tested for syntactic correctness and are formatted automatically according to the Ada style guide, yet the text all appears to the right of --C's.

The transform comment-out can be used to embed an arbitrary group of compilation units or statements inside this special form of comment. The transform uncomment-out reverses the process.

Automatic Movement of Comments

The rules of Ada permit a comment to appear between any two tokens. Ada-ASSURED restricts the positions of comments according to its style rules. When a file is opened that was created using another editor, comments may be encountered at locations where they are not permitted by Ada-ASSURED. Such comments will never be discarded, but may be moved to either:

• a line of their own, or

• the right of a construct displayed on its own line, e.g., a statement or declaration.

Area := (22 / 7) -- approximation to pi
              * R ** 2;

Area := 22 / 7 * R ** 2;
-- approximation to pi

Marker Comments

Comments after end if, end case, and else are called marker comments. The SPC style guide suggests the use of marker comments for long or deeply nested if and case statements. Enforcement parameters can be set to require the use of marker comments depending on either the lines of code or the nesting depth of an if or case.

Header Comments

The templates built into Ada-ASSURED can be customized and extended to support project-specific headers, i.e., comments that document a file or construct in a standard format. For example, the built-in transform procedure-body just inserts the generic Ada code template:

--~--------------------------------------------------------------

procedure <identifier> is

    <basic_declarative_item>

begin
    <statement>
end ;

--~--------------------------------------------------------------

--~--------------------------------------------------------------

procedure <identifier> is

    --------------------------------------------------------
    --# CSU
    --
    --# extract error_handling
    --# <Describe any error handling here.>
    --# end
    --------------------------------------------------------

    <basic_declarative_item>

begin
    --| PDL begins here
    --| PDL ends here
    <statement>
end ;

--~--------------------------------------------------------------

Ada-ASSURED is distributed with several sample header libraries that illustrate how to define your own:

• aahome/scripts/adl.headers.stk
• aahome/scripts/boeing.headers.stk.