3psoccon.ads, [...]: Files added.

[thirdparty/gcc.git] / gcc / ada / atree.ads

diff --git a/gcc/ada/atree.ads b/gcc/ada/atree.ads
index b9d2b9b26f146ea4d6ba3e0400bac599eeaf6a4e..e24d65d5b325c8d47e64f14152b64a10f7babc35 100644 (file)
--- a/gcc/ada/atree.ads
+++ b/gcc/ada/atree.ads
@@ -6,7 +6,7 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
---          Copyright (C) 1992-2001, Free Software Foundation, Inc.         --
+--          Copyright (C) 1992-2003, Free Software Foundation, Inc.         --
 --                                                                          --
 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
 -- terms of the  GNU General Public License as published  by the Free Soft- --
@@ -148,7 +148,7 @@ package Atree is
    --   package in Atree allows for direct untyped accesses in such cases.
 
    --   Flag4            Fifteen Boolean flags (use depends on Nkind and
-   --   Flag5            Ekind, as described for Fieldn). Again the access
+   --   Flag5            Ekind, as described for FieldN). Again the access
    --   Flag6            is usually via subprograms in Sinfo and Einfo which
    --   Flag7            provide high-level synonyms for these flags, and
    --   Flag8            contain debugging code that checks that the values
@@ -242,9 +242,9 @@ package Atree is
    --  avoid posting related cascaded error messages, and to propagate
    --  the error node if necessary.
 
-   -----------------------
+   ------------------------
    -- Current_Error_Node --
-   -----------------------
+   ------------------------
 
    --  The current error node is a global location indicating the current
    --  node that is being processed for the purposes of placing a compiler
@@ -252,7 +252,15 @@ package Atree is
    --  just a reasonably accurate best guess. It is used to output the
    --  source location in the abort message by Comperr, and also to
    --  implement the d3 debugging flag. This is also used by Rtsfind
-   --  to generate error messages for No_Run_Time mode.
+   --  to generate error messages for high integrity mode.
+
+   --  There are two ways this gets set. During parsing, when new source
+   --  nodes are being constructed by calls to New_Node and New_Entity,
+   --  either one of these calls sets Current_Error_Node to the newly
+   --  created node. During semantic analysis, this mechanism is not
+   --  used, and instead Current_Error_Node is set by the subprograms in
+   --  Debug_A that mark the start and end of analysis/expansion of a
+   --  node in the tree.
 
    Current_Error_Node : Node_Id;
    --  Node to place error messages
@@ -285,7 +293,7 @@ package Atree is
 
    --  A subpackage Atree.Unchecked_Access provides routines for reading and
    --  writing the fields defined above (Field1-17, Node1-17, Flag1-88 etc).
-   --  These unchecked access routines can be used for untyped traversals. In
+   --  These unchecked access routines can be used for untyped traversals.
    --  In addition they are used in the implementations of the Sinfo and
    --  Einfo packages. These packages both provide logical synonyms for
    --  the generic fields, together with an appropriate set of access routines.
@@ -329,13 +337,17 @@ package Atree is
    --  Allocates a completely new node with the given node type and source
    --  location values. All other fields are set to their standard defaults:
    --
-   --    Empty for all Fieldn fields
-   --    False for all Flagn fields
+   --    Empty for all FieldN fields
+   --    False for all FlagN fields
    --
    --  The usual approach is to build a new node using this function and
    --  then, using the value returned, use the Set_xxx functions to set
    --  fields of the node as required. New_Node can only be used for
    --  non-entity nodes, i.e. it never generates an extended node.
+   --
+   --  If we are currently parsing, as indicated by a previous call to
+   --  Set_Comes_From_Source_Default (True), then this call also resets
+   --  the value of Current_Error_Node.
 
    function New_Entity
      (New_Node_Kind : Node_Kind;
@@ -347,7 +359,9 @@ package Atree is
    procedure Set_Comes_From_Source_Default (Default : Boolean);
    --  Sets value of Comes_From_Source flag to be used in all subsequent
    --  New_Node and New_Entity calls until another call to this procedure
-   --  changes the default.
+   --  changes the default. This value is set True during parsing and
+   --  False during semantic analysis. This is also used to determine
+   --  if New_Node and New_Entity should set Current_Error_Node.
 
    function Get_Comes_From_Source_Default return Boolean;
    pragma Inline (Get_Comes_From_Source_Default);