sinfo.ads (Is_Scil_Node, [...]): Add missing documentation.

2009-07-23  Javier Miranda  <miranda@adacore.com>

	* sinfo.ads (Is_Scil_Node, Scil_Nkind, Scil_Related_Node,
	Scil_Target_Prim, N_Has_Entity): Add missing documentation.
	* exp_disp.ads (Scil_Node_Kind): Ditto.
	* exp_disp.adb (Make_DT, Make_Tags): Ditto.
	* exp_ch3.adb (Build_Init_Procedure): Ditto.

From-SVN: r149982

5 files changed, 79 insertions, 19 deletions

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index bbb9f64..8a119ac 100644
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,5 +1,13 @@
 2009-07-23  Javier Miranda  <miranda@adacore.com>
 
+	* sinfo.ads (Is_Scil_Node, Scil_Nkind, Scil_Related_Node,
+	Scil_Target_Prim, N_Has_Entity): Add missing documentation.
+	* exp_disp.ads (Scil_Node_Kind): Ditto.
+	* exp_disp.adb (Make_DT, Make_Tags): Ditto.
+	* exp_ch3.adb (Build_Init_Procedure): Ditto.
+
+2009-07-23  Javier Miranda  <miranda@adacore.com>
+
 	* einfo.adb (Component_Type): Add missing assertion.
 	* sem_res.adb (Resolve_Call): Ensure proper kind of entity before
 	reading attribute Component_Size.
diff --git a/gcc/ada/exp_ch3.adb b/gcc/ada/exp_ch3.adb
index fe51d2f..51dccfb 100644
--- a/gcc/ada/exp_ch3.adb
+++ b/gcc/ada/exp_ch3.adb
@@ -1409,8 +1409,8 @@ package body Exp_Ch3 is
 
       if (Is_Null_Init_Proc (Proc) and then not Init_Or_Norm_Scalars)
         or else Is_Value_Type (Typ)
-        or else ((Is_Array_Type (Typ) or else Is_String_Type (Typ))
-                    and then Is_Value_Type (Component_Type (Typ)))
+        or else
+          (Is_Array_Type (Typ) and then Is_Value_Type (Component_Type (Typ)))
       then
          return Empty_List;
       end if;
@@ -2323,7 +2323,8 @@ package body Exp_Ch3 is
                   New_Reference_To
                     (Node (First_Elmt (Access_Disp_Table (Rec_Type))), Loc)));
 
-            --  Following code needs a comment ???
+            --  Generate the SCIL node associated with the initialization of
+            --  the tag component.
 
             if Generate_SCIL then
                Prepend_To (Init_Tags_List,
diff --git a/gcc/ada/exp_disp.adb b/gcc/ada/exp_disp.adb
index 5e70038..104b1c0 100644
--- a/gcc/ada/exp_disp.adb
+++ b/gcc/ada/exp_disp.adb
@@ -643,7 +643,7 @@ package body Exp_Disp is
          Typ := Non_Limited_View (Typ);
       end if;
 
-      --  Comment needed ???
+      --  Generate the SCIL node of this dispatching call
 
       if Generate_SCIL then
          Insert_Action (Call_Node,
@@ -4243,7 +4243,8 @@ package body Exp_Disp is
                   New_Reference_To
                     (RTE (RE_No_Dispatch_Table_Wrapper), Loc)));
 
-            --  Comment needed ???
+            --  Generate a SCIL node for the previous object declaration
+            --  because it has a null dispatch table.
 
             if Generate_SCIL then
                Insert_Before (Last (Result),
@@ -4279,6 +4280,9 @@ package body Exp_Disp is
                             (RTE_Record_Component (RE_NDT_Prims_Ptr), Loc)),
                       Attribute_Name => Name_Address))));
 
+            --  Generate the SCIL node for the previous object declaration
+            --  because it has a tag initialization.
+
             if Generate_SCIL then
                Insert_Before (Last (Result),
                  New_Scil_Node
@@ -4316,7 +4320,8 @@ package body Exp_Disp is
                     Constraint => Make_Index_Or_Discriminant_Constraint (Loc,
                                     Constraints => DT_Constr_List))));
 
-            --  Comment needed ???
+            --  Generate the SCIL node for the previous object declaration
+            --  because it contains a dispatch table.
 
             if Generate_SCIL then
                Insert_Before (Last (Result),
@@ -4352,7 +4357,8 @@ package body Exp_Disp is
                             (RTE_Record_Component (RE_Prims_Ptr), Loc)),
                       Attribute_Name => Name_Address))));
 
-            --  Comment needed ???
+            --  Generate the SCIL node for the previous object declaration
+            --  because it has a tag initialization.
 
             if Generate_SCIL then
                Insert_Before (Last (Result),
@@ -5130,7 +5136,8 @@ package body Exp_Disp is
                 Expression => Make_Aggregate (Loc,
                   Expressions => DT_Aggr_List)));
 
-            --  Comment needed ???
+            --  Generate the SCIL node for the previous object declaration
+            --  because it has a null dispatch table.
 
             if Generate_SCIL then
                Insert_Before (Last (Result),
@@ -5446,7 +5453,8 @@ package body Exp_Disp is
                 Expression => Make_Aggregate (Loc,
                   Expressions => DT_Aggr_List)));
 
-            --  Comment needed ???
+            --  Generate the SCIL node for the previous object declaration
+            --  because it contains a dispatch table.
 
             if Generate_SCIL then
                Insert_Before (Last (Result),
@@ -6146,7 +6154,8 @@ package body Exp_Disp is
                             (RTE_Record_Component (RE_Prims_Ptr), Loc)),
                       Attribute_Name => Name_Address))));
 
-            --  Comment needed ???
+            --  Generate the SCIL node for the previous object declaration
+            --  because it has a tag initialization.
 
             if Generate_SCIL then
                Insert_Before (Last (Result),
@@ -6191,7 +6200,8 @@ package body Exp_Disp is
                             (RTE_Record_Component (RE_NDT_Prims_Ptr), Loc)),
                       Attribute_Name => Name_Address))));
 
-            --  Comment needed ???
+            --  Generate the SCIL node for the previous object declaration
+            --  because it has a tag initialization.
 
             if Generate_SCIL then
                Insert_Before (Last (Result),
diff --git a/gcc/ada/exp_disp.ads b/gcc/ada/exp_disp.ads
index 05609c3..e02cca7 100644
--- a/gcc/ada/exp_disp.ads
+++ b/gcc/ada/exp_disp.ads
@@ -34,7 +34,24 @@ package Exp_Disp is
    -- SCIL Node Type Definition --
    -------------------------------
 
-   --  Comment required! ??? What is this type???
+   --  SCIL nodes are a special kind of nodes added to the tree when the
+   --  CodePeer mode is active. They are stored in the tree as special
+   --  N_Null_Statement nodes that have extra attributes. The information
+   --  available through these extra attributes relies on the kind of SCIL
+   --  node. The SCIL node kind is stored in the Scil_Nkind attribute of
+   --  the N_Null_Statement node. The kind of SCIL nodes generated by the
+   --  frontend are the following:
+
+   --    IP_Tag_Init: Scil node of tag component initialization.
+
+   --    Dispatching_Call: Scil node of dispatching call. Used by the
+   --      CodePeer backend to locate nodes associated with dispatching
+   --      calls.
+
+   --    Dispatching_Table_Object_Init: Scil node of object declaration
+   --      containing a dispatch table.
+
+   --    Dispatching_Table_Tag_Init: Scil node of tag initialization.
 
    type Scil_Node_Kind is
      (Unused,
diff --git a/gcc/ada/sinfo.ads b/gcc/ada/sinfo.ads
index 213812d..9d42a51 100644
--- a/gcc/ada/sinfo.ads
+++ b/gcc/ada/sinfo.ads
@@ -1251,6 +1251,15 @@ package Sinfo is
    --    handler to make sure that the associated protected object is unlocked
    --    when the subprogram completes.
 
+   --  Is_Scil_Node (Flag4-Sem)
+   --    Present in N_Null_Statement nodes. Set to indicate that it is a SCIL
+   --    node. Scil nodes are special nodes that help the CodePeer backend
+   --    locating nodes that require special processing. In order to minimize
+   --    the impact on the compiler and ASIS, and also to maximize flexibility
+   --    when adding SCIl nodes to the tree, instead of adding new kind of
+   --    nodes, SCIL nodes are added to the tree as N_Null_Statement nodes on
+   --    which this attribute is set.
+
    --  Is_Static_Coextension (Flag14-Sem)
    --    Present in N_Allocator nodes. Set if the allocator is a coextension
    --    of an object allocated on the stack rather than the heap.
@@ -1589,6 +1598,19 @@ package Sinfo is
    --    are the result of expansion of rounded fixed-point divide, conversion
    --    and multiplication operations.
 
+   --  Scil_Nkind (Uint3-Sem)
+   --    Present in N_Null_Statement nodes that are Scil nodes. Used to
+   --    indicate the kind of SCIL node (see scil node kinds in exp_disp.ads).
+
+   --  Scil_Related_Node (Node1-Sem)
+   --    Present in N_Null_Statement nodes that are Scil nodes. Used to
+   --    reference a tree node that requires special processing in the
+   --    CodePeer backend.
+
+   --  Scil_Target_Prim (Node2-Sem)
+   --    Present in N_Null_Statement nodes. Used to reference the tagged type
+   --    primitive associated with the SCIL node.
+
    --  Scope (Node3-Sem)
    --    Present in defining identifiers, defining character literals and
    --    defining operator symbols (i.e. in all entities). The entities of a
@@ -3842,11 +3864,9 @@ package Sinfo is
       --  Entity (Node4-Sem)
       --  Scil_Target_Prim (Node2-Sem)
 
-      --  What are the above Scil fields for, and what has this got to do with
-      --  null statements. MAJOR MISSING DOC HERE ??? All -Sem fields must be
-      --  individually documented in the list of -Sem fields at the start of
-      --  Sinfo, and we sure need significant documentation here explaining
-      --  what on earth is going on with null statements!
+      --  Note that in SCIL nodes (N_Null_Statement nodes with Is_Scil_Node
+      --  set to True), Entity references the tagged type associated with
+      --  the SCIL node.
 
       ----------------
       -- 5.1  Label --
@@ -7240,8 +7260,6 @@ package Sinfo is
       N_Goto_Statement,
       N_Loop_Statement,
       N_Null_Statement,
-      --  N_Null_Statement now has an Entity field, but is not in N_Has_Entity.
-      --  Either fix this, or document this peculiar irregularity ???
       N_Raise_Statement,
       N_Requeue_Statement,
       N_Return_Statement, -- renamed as N_Simple_Return_Statement below
@@ -7413,6 +7431,12 @@ package Sinfo is
    --  Nodes that have Entity fields
    --  Warning: DOES NOT INCLUDE N_Freeze_Entity!
 
+   --  Warning: DOES NOT INCLUDE N_Null_Assignment because it not always
+   --  available. The Entity attribute is only available in Scil nodes
+   --  (that is, N_Null_Assignment nodes that have Is_Scil_Node set to true).
+   --  Processing such nodes never requires testing if the node is in
+   --  N_Has_Entity node kind.
+
    subtype N_Has_Etype is Node_Kind range
      N_Error ..
      N_Subtype_Indication;