* get_scos.adb, par_sco.adb, par_sco.ads, put_scos.adb, scos.adb,

	scos.ads, exp_ch4.adb, sem_warn.adb: Code clean up, update
	documentation.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@160849 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 81 insertions, 30 deletions

diff --git a/gcc/ada/scos.ads b/gcc/ada/scos.ads
index 19804e4567b..9e6a973a0cd 100644
--- a/gcc/ada/scos.ads
+++ b/gcc/ada/scos.ads
@@ -148,21 +148,27 @@ package SCOs is
    --      o  object declaration
    --      r  renaming declaration
    --      i  generic instantiation
-   --      C  CASE statement (includes only the expression)
+   --      C  CASE statement (from CASE through end of expression)
    --      E  EXIT statement
-   --      F  FOR loop statement (includes only the iteration scheme)
-   --      I  IF statement (includes only the condition [in the RM sense, which
-   --         is a decision in the SCO sense])
+   --      F  FOR loop statement (from FOR through end of iteration scheme)
+   --      I  IF statement (from IF through end of condition)
    --      P  PRAGMA
    --      R  extended RETURN statement
-   --      W  WHILE loop statement (includes only the condition)
+   --      W  WHILE loop statement (from WHILE through end of condition)
+
+   --      Note: for I and W, condition above is in the RM syntax sense (this
+   --      condition is a decision in SCO terminology).
 
    --    and is omitted for all other cases.
 
+   --  Note: up to 6 entries can appear on a single CS line. If more than 6
+   --  entries appear in one logical statement sequence, continuation lines are
+   --  marked by Cs and appear immediately after the CS line they continue.
+
    --  Decisions
 
    --    Note: in the following description, logical operator includes only the
-   --    short circuited forms and NOT (so can be only NOT, AND THEN, OR ELSE).
+   --    short-circuited forms and NOT (so can be only NOT, AND THEN, OR ELSE).
    --    The reason that we can exclude AND/OR/XOR is that we expect SCO's to
    --    be generated using the restriction No_Direct_Boolean_Operators if we
    --    are interested in decision coverage, which does not permit the use of
@@ -171,18 +177,27 @@ package SCOs is
    --    we are generating SCO's only for simple coverage, then we are not
    --    interested in decisions in any case.
 
-   --    Decisions are either simple or complex. A simple decision is a boolean
-   --    expresssion that occurs in the context of a control structure in the
-   --    source program, including WHILE, IF, EXIT WHEN, or in an Assert,
-   --    Check, Pre_Condition or Post_Condition pragma. For pragmas, decision
-   --    SCOs are generated only if the corresponding pragma is enabled. Note
-   --    that a boolean expression in any other context, for example as right
-   --    hand side of an assignment, is not considered to be a simple decision.
+   --    Note: the reason we include NOT is for informational purposes. The
+   --    presence of NOT does not generate additional coverage obligations,
+   --    but if we know where the NOT's are, the coverage tool can generate
+   --    more accurate diagnostics on uncovered tests.
+
+   --    A top level boolean expression is a boolean expression that is not an
+   --    operand of a logical operator.
+
+   --    Decisions are either simple or complex. A simple decision is a top
+   --    level boolean expresssion that has only one condition and that occurs
+   --    in the context of a control structure in the source program, including
+   --    WHILE, IF, EXIT WHEN, or in an Assert, Check, Pre_Condition or
+   --    Post_Condition pragma. For pragmas, decision SCOs are generated only
+   --    if the corresponding pragma is enabled. Note that a top level boolean
+   --    expression with only one condition that occurs in any other context,
+   --    for example as right hand side of an assignment, is not considered to
+   --    be a (simple) decision.
 
-   --    A complex decision is an occurrence of a logical operator which is not
-   --    itself an operand of some other logical operator. If any operand of
-   --    the logical operator is itself a logical operator, this is not a
-   --    separate decision, it is part of the same decision.
+   --    A complex decision is a top level boolean expression that has more
+   --    than one condition. A complex decision may occur in any boolean
+   --    expression context.
 
    --    So for example, if we have
 
@@ -201,7 +216,7 @@ package SCOs is
 
    --    For each decision, a decision line is generated with the form:
 
-   --      C*sloc expression
+   --      C* sloc expression
 
    --    Here * is one of the following characters:
 
@@ -217,7 +232,7 @@ package SCOs is
    --    For X, sloc is omitted.
 
    --    The expression is a prefix polish form indicating the structure of
-   --    the decision, including logical operators and short circuit forms.
+   --    the decision, including logical operators and short-circuit forms.
    --    The following is a grammar showing the structure of expression:
 
    --      expression ::= term             (if expr is not logical operator)
@@ -248,8 +263,14 @@ package SCOs is
 
    --    ! indicates NOT applied to the expression.
 
-   --    In the context of Couverture, the No_Direct_Boolean_Opeartors
-   --    restriction is assumed, and no other operator can appear.
+   --    Note that complex decisions do NOT include non-short-circuited logical
+   --    operators (AND/XOR/OR). In the context of existing coverage tools the
+   --    No_Direct_Boolean_Operators restriction is assumed, so these operators
+   --    cannot appear in the source in any case.
+
+   --    The SCO line for a decision always occurs after the CS line for the
+   --    enclosing statement. The SCO line for a nested decision always occurs
+   --    after the line for the enclosing decision.
 
    ---------------------------------------------------------------------
    -- Internal table used to store Source Coverage Obligations (SCOs) --
@@ -265,6 +286,7 @@ package SCOs is
    type SCO_Table_Entry is record
       From : Source_Location;
       To   : Source_Location;
+      Node : Node_Id;
       C1   : Character;
       C2   : Character;
       Last : Boolean;
@@ -284,27 +306,55 @@ package SCOs is
    --      C2   = statement type code to appear on CS line (or ' ' if none)
    --      From = starting source location
    --      To   = ending source location
+   --      Node = Empty
    --      Last = False for all but the last entry, True for last entry
 
    --    Note: successive statements (possibly interspersed with entries of
    --    other kinds, that are ignored for this purpose), starting with one
    --    labeled with C1 = 'S', up to and including the first one labeled with
-   --    Last=True, indicate the sequence to be output for a sequence of
-   --    statements on a single CS line.
+   --    Last = True, indicate the sequence to be output for a sequence of
+   --    statements on a single CS line (possibly followed by Cs continuation
+   --    lines).
+
+   --    Decision (IF/EXIT/WHILE)
+   --      C1   = 'I'/'E'/'W' (for IF/EXIT/WHILE)
+   --      C2   = ' '
+   --      From = IF/EXIT/WHILE token
+   --      To   = No_Source_Location
+   --      Node = Empty
+   --      Last = unused
+
+   --    Decision (PRAGMA)
+   --      C1   = 'P'
+   --      C2   = ' '
+   --      From = PRAGMA token
+   --      To   = No_Source_Location
+   --      Node = N_Pragma node or Empty when reading SCO data (see below)
+   --      Last = unused
 
-   --    Decision
-   --      C1   = decision type code
+   --      Note: when the parse tree is first scanned, we unconditionally build
+   --      a pragma decision entry for any decision in a pragma (here as always
+   --      in SCO contexts, the only relevant pragmas are Assert, Check,
+   --      Precondition and Postcondition). Then when we output the SCO info
+   --      to the ALI file, we use the Node field to check the Pragma_Enabled
+   --      flag, and if it is False, we suppress output of the pragma decision
+   --      line. On reading back SCO data from an ALI file, the Node field is
+   --      always set to Empty.
+
+   --    Decision (Expression)
+   --      C1   = 'X'
    --      C2   = ' '
-   --      From = location of IF/EXIT/PRAGMA/WHILE token,
-   --             No_Source_Location for X
+   --      From = No_Source_Location
    --      To   = No_Source_Location
+   --      Node = Empty
    --      Last = unused
 
    --    Operator
-   --      C1   = '!', '^', '&', '|'
+   --      C1   = '!', '&', '|'
    --      C2   = ' '
    --      From = location of NOT/AND/OR token
    --      To   = No_Source_Location
+   --      Node = Empty
    --      Last = False
 
    --    Element (condition)
@@ -312,12 +362,12 @@ package SCOs is
    --      C2   = 'c', 't', or 'f' (condition/true/false)
    --      From = starting source location
    --      To   = ending source location
+   --      Node = Empty
    --      Last = False for all but the last entry, True for last entry
 
    --    Note: the sequence starting with a decision, and continuing with
    --    operators and elements up to and including the first one labeled with
-   --    Last = True, indicate the sequence to be output for a complex decision
-   --    on a single CD decision line.
+   --    Last = True, indicate the sequence to be output on one decision line.
 
    ----------------
    -- Unit Table --
@@ -365,6 +415,7 @@ package SCOs is
       To   : Source_Location := No_Source_Location;
       C1   : Character       := ' ';
       C2   : Character       := ' ';
+      Node : Node_Id         := Empty;
       Last : Boolean         := False);
    --  Adds one entry to SCO table with given field values