sem_ch3.adb, [...]: Update comments.

2011-08-02  Robert Dewar  <dewar@adacore.com>

	* sem_ch3.adb, exp_atag.ads, get_scos.adb, get_scos.ads,
	exp_disp.adb, lib-xref.adb, lib-xref.ads: Update comments.
	Minor reformatting.

From-SVN: r177169

8 files changed, 161 insertions, 157 deletions

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index 0890b26..152af3e 100644
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,5 +1,11 @@
 2011-08-02  Robert Dewar  <dewar@adacore.com>
 
+	* sem_ch3.adb, exp_atag.ads, get_scos.adb, get_scos.ads,
+	exp_disp.adb, lib-xref.adb, lib-xref.ads: Update comments.
+	Minor reformatting.
+
+2011-08-02  Robert Dewar  <dewar@adacore.com>
+
 	* sem_res.adb: Minor reformatting.
 	* sem_prag.adb: Minor reformatting.
 
diff --git a/gcc/ada/exp_atag.ads b/gcc/ada/exp_atag.ads
index 586904b..657e53f 100644
--- a/gcc/ada/exp_atag.ads
+++ b/gcc/ada/exp_atag.ads
@@ -40,6 +40,7 @@ package Exp_Atag is
       Stmts : List_Id);
    --  Ada 2005 (AI-345): Generate statements that are common between timed,
    --  asynchronous, and conditional select expansion.
+   --  Comments required saying what parameters mean ???
 
    procedure Build_CW_Membership
      (Loc          : Source_Ptr;
diff --git a/gcc/ada/exp_disp.adb b/gcc/ada/exp_disp.adb
index 4f0fc0f..6c8642b 100644
--- a/gcc/ada/exp_disp.adb
+++ b/gcc/ada/exp_disp.adb
@@ -594,7 +594,7 @@ package body Exp_Disp is
                Analyze_List (Target_List);
 
                if Present (Priv_Decls)
-                  and then Is_Non_Empty_List (Priv_Decls)
+                 and then Is_Non_Empty_List (Priv_Decls)
                then
                   Append_List (Target_List, Priv_Decls);
                else
@@ -6804,7 +6804,7 @@ package body Exp_Disp is
                   if Tagged_Type_Expansion then
                      Tag_Node :=
                        New_Reference_To
-                        (Node (First_Elmt (Access_Disp_Table (Typ))), Loc);
+                         (Node (First_Elmt (Access_Disp_Table (Typ))), Loc);
                   else
                      Tag_Node :=
                        Make_Attribute_Reference (Loc,
diff --git a/gcc/ada/get_scos.adb b/gcc/ada/get_scos.adb
index 074c658..7a90959 100644
--- a/gcc/ada/get_scos.adb
+++ b/gcc/ada/get_scos.adb
@@ -6,7 +6,7 @@
 --                                                                          --
 --                                 B o d y                                  --
 --                                                                          --
---           Copyright (C) 2009-2011, Free Software Foundation, Inc.        --
+--          Copyright (C) 2009-2011, 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- --
diff --git a/gcc/ada/get_scos.ads b/gcc/ada/get_scos.ads
index f440b22..065a297 100644
--- a/gcc/ada/get_scos.ads
+++ b/gcc/ada/get_scos.ads
@@ -6,7 +6,7 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
---           Copyright (C) 2009-2011, Free Software Foundation, Inc.        --
+--          Copyright (C) 2009-2011, 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- --
diff --git a/gcc/ada/lib-xref.adb b/gcc/ada/lib-xref.adb
index d44f1b8..b683da0 100644
--- a/gcc/ada/lib-xref.adb
+++ b/gcc/ada/lib-xref.adb
@@ -330,12 +330,12 @@ package body Lib.Xref is
          return;
       end if;
 
-      --  Ada 2005 (AI-345): For synchronized types generate reference
-      --  to the wrapper that allow us to dispatch calls through their
-      --  implemented abstract interface types.
+      --  Ada 2005 (AI-345): For synchronized types generate reference to the
+      --  wrapper that allow us to dispatch calls through their implemented
+      --  abstract interface types.
 
-      --  The check for Present here is to protect against previously
-      --  reported critical errors.
+      --  The check for Present here is to protect against previously reported
+      --  critical errors.
 
       Prim_List := Primitive_Operations (Base_T);
 
@@ -1042,8 +1042,11 @@ package body Lib.Xref is
 
    function Is_Local_Reference_Type (Typ : Character) return Boolean is
    begin
-      return Typ = 'r' or else Typ = 'm' or else Typ = 's'
-        or else Typ = 'I' or else Typ = 'D';
+      return Typ = 'r' or else
+             Typ = 'm' or else
+             Typ = 's' or else
+             Typ = 'I' or else
+             Typ = 'D';
    end Is_Local_Reference_Type;
 
    --------
@@ -1321,8 +1324,8 @@ package body Lib.Xref is
          return;
       end if;
 
-      --  First we add references to the primitive operations of tagged
-      --  types declared in the main unit.
+      --  First we add references to the primitive operations of tagged types
+      --  declared in the main unit.
 
       Handle_Prim_Ops : declare
          Ent  : Entity_Id;
@@ -1990,16 +1993,16 @@ package body Lib.Xref is
                --  specs.
 
                  or else (XE.Loc = XE.Def
-                            and then
-                              (XE.Typ /= 'b'
-                                or else not Is_Subprogram (XE.Ent)))
+                           and then
+                             (XE.Typ /= 'b'
+                               or else not Is_Subprogram (XE.Ent)))
 
                --  Also suppress definitions of body formals (we only
                --  treat these as references, and the references were
                --  separately recorded).
 
                  or else (Is_Formal (XE.Ent)
-                            and then Present (Spec_Entity (XE.Ent)))
+                           and then Present (Spec_Entity (XE.Ent)))
                then
                   null;
 
@@ -2400,11 +2403,10 @@ package body Lib.Xref is
       --  not suitable for local cross-references.
 
       Rnums : array (0 .. Nrefs) of Nat;
-      --  This array contains numbers of references in the Xrefs table.
-      --  This list is sorted in output order. The extra 0'th entry is
-      --  convenient for the call to sort. When we sort the table, we
-      --  move the entries in Rnums around, but we do not move the
-      --  original table entries.
+      --  This array contains numbers of references in the Xrefs table. This
+      --  list is sorted in output order. The extra 0'th entry is convenient
+      --  for the call to sort. When we sort the table, we move the entries in
+      --  Rnums around, but we do not move the original table entries.
 
       Curxu : Unit_Number_Type;
       --  Current xref unit
@@ -2555,9 +2557,9 @@ package body Lib.Xref is
       begin
          --  Eliminate duplicate entries
 
-         --  We need this test for NR because if we force ALI file
-         --  generation in case of errors detected, it may be the case
-         --  that Nrefs is 0, so we should not reset it here
+         --  We need this test for NR because if we force ALI file generation
+         --  in case of errors detected, it may be the case that Nrefs is zero,
+         --  so we should not reset it here.
 
          if Nrefs >= 2 then
             NR    := Nrefs;
@@ -2602,6 +2604,7 @@ package body Lib.Xref is
       for Refno in 1 .. Nrefs loop
          Output_One_Ref : declare
             Ent : Entity_Id;
+
             XE  : Xref_Entry renames Xrefs.Table (Rnums (Refno));
             --  The current entry to be accessed
 
@@ -2644,8 +2647,8 @@ package body Lib.Xref is
                Write_Info_Char (' ');
                Write_Entity_Name (XE.Sub, Cursrc);
 
-               --  Indicate that the entity is in the unit of the current
-               --  local xref section.
+               --  Indicate that the entity is in the unit of the current local
+               --  xref section.
 
                Curru := Cursu;
 
@@ -2676,17 +2679,15 @@ package body Lib.Xref is
                Curru := Cursu;
             end if;
 
-            --  Start new Entity line if new entity. Note that we
-            --  consider two entities the same if they have the same
-            --  name and source location. This causes entities in
-            --  instantiations to be treated as though they referred
-            --  to the template.
+            --  Start new Entity line if new entity. Note that we consider two
+            --  entities the same if they have the same name and source
+            --  location. This causes entities in instantiations to be treated
+            --  as though they referred to the template.
 
             if No (Curent)
               or else
                 (XE.Ent /= Curent
-                 and then
-                   (Name_Change (XE.Ent) or else XE.Def /= Curdef))
+                  and then (Name_Change (XE.Ent) or else XE.Def /= Curdef))
             then
                Curent := XE.Ent;
                Curdef := XE.Def;
@@ -2715,14 +2716,14 @@ package body Lib.Xref is
                Crloc := No_Location;
             end if;
 
-            --  Output the reference if it is not as the same location
-            --  as the previous one, or it is a read-reference that
-            --  indicates that the entity is an in-out actual in a call.
+            --  Output the reference if it is not as the same location as the
+            --  previous one, or it is a read-reference that indicates that the
+            --  entity is an in-out actual in a call.
 
             if XE.Loc /= No_Location
               and then
                 (XE.Loc /= Crloc
-                 or else (Prevt = 'm' and then XE.Typ = 'r'))
+                  or else (Prevt = 'm' and then XE.Typ = 'r'))
             then
                Crloc := XE.Loc;
                Prevt := XE.Typ;
@@ -2804,10 +2805,9 @@ package body Lib.Xref is
             end if;
          end loop;
 
-         --  Write out the identifier by copying the exact
-         --  source characters used in its declaration. Note
-         --  that this means wide characters will be in their
-         --  original encoded form.
+         --  Write out the identifier by copying the exact source characters
+         --  used in its declaration. Note that this means wide characters will
+         --  be in their original encoded form.
 
          for J in
            Original_Location (Sloc (E)) .. P - 1
diff --git a/gcc/ada/lib-xref.ads b/gcc/ada/lib-xref.ads
index 1d0749c..829e8723 100644
--- a/gcc/ada/lib-xref.ads
+++ b/gcc/ada/lib-xref.ads
@@ -44,7 +44,7 @@ package Lib.Xref is
    --        This header precedes xref information (entities/references from
    --        the unit), identified by dependency number and file name. The
    --        dependency number is the index into the generated D lines and
-   --        its origin is one (i.e. 2 = reference to second generated D line).
+   --        is ones origin (e.g. 2 = reference to second generated D line).
 
    --        Note that the filename here will reflect the original name if
    --        a Source_Reference pragma was encountered (since all line number
@@ -61,17 +61,17 @@ package Lib.Xref is
    --        if the entity is the first token on the line, and is preceded
    --        by space-HT-space, then the column would be column 10.
 
-   --        type is a single letter identifying the type of the entity.
-   --        See next section (Cross-Reference Entity Identifiers) for a
-   --        full list of the characters used).
+   --        type is a single letter identifying the type of the entity. See
+   --        next section (Cross-Reference Entity Identifiers) for a full list
+   --        of the characters used).
 
    --        col is the column number of the referenced entity
 
-   --        level is a single character that separates the col and
-   --        entity fields. It is an asterisk (*) for a top level library
-   --        entity that is publicly visible, as well as for an entity declared
-   --        in the visible part of a generic package, the plus sign (+) for
-   --        a C/C++ static entity, and space otherwise.
+   --        level is a single character that separates the col and entity
+   --        fields. It is an asterisk (*) for a top level library entity that
+   --        is publicly visible, as well for an entity declared in the visible
+   --        part of a generic package, the plus sign (+) for a C/C++ static
+   --        entity, and space otherwise.
 
    --        entity is the name of the referenced entity, with casing in
    --        the canonical casing for the source file where it is defined.
@@ -84,24 +84,23 @@ package Lib.Xref is
 
    --            =line:col
 
-   --        Here line:col give the reference to the identifier that
-   --        appears in the renaming declaration. Note that we never need
-   --        a file entry, since this identifier is always in the current
-   --        file in which the entity is declared. Currently, renameref
-   --        appears only for the simple renaming case. If the renaming
-   --        reference is a complex expressions, then renameref is omitted.
-   --        Here line/col give line/column as defined above.
+   --        Here line:col give the reference to the identifier that appears
+   --        in the renaming declaration. Note that we never need a file entry,
+   --        since this identifier is always in the current file in which the
+   --        entity is declared. Currently, renameref appears only for the
+   --        simple renaming case. If the renaming reference is a complex
+   --        expressions, then renameref is omitted. Here line/col give
+   --        line/column as defined above.
 
-   --        instref is only present for package and subprogram instances.
-   --        The information in instref is the location of the point of
-   --        declaration of the generic parent unit. This part has the form:
+   --        instref is only present for package and subprogram instances. The
+   --        information in instref is the location of the point of declaration
+   --        of the generic parent unit. This part has the form:
 
    --            [file|line]
 
    --        without column information, on the reasonable assumption that
-   --        there is only one unit per line (the same assumption is made
-   --        in references to entities that are declared within instances,
-   --        see below).
+   --        there is only one unit per line (the same assumption is made in
+   --        references to entities declared within instances, see below).
 
    --        typeref is the reference for a related type. This part is
    --        optional. It is present for the following cases:
@@ -122,15 +121,15 @@ package Lib.Xref is
    --          additional interfaces are stored in the list of references
    --          with a special type of Interface_Reference.
 
-   --          For an array type, there is an entry of the form LR=<> for
-   --          each of the index types appearing in the type declaration.
-   --          The index types follow the entry for the component type.
-   --          In the data structures of ali.ads, however, the list of index
-   --          types are output in the list of references with a special
-   --          Rtype set to Array_Index_Reference.
+   --          For an array type, there is an entry of the form LR=<> for each
+   --          of the index types appearing in the type declaration. The index
+   --          types follow the entry for the component type. In the data
+   --          structures of ali.ads, however, the list of index types are
+   --          output in the list of references with a special Rtype set to
+   --          Array_Index_Reference.
 
-   --          In the above list LR shows the brackets used in the output,
-   --          which has one of the two following forms:
+   --          In the above list LR shows the brackets used in the output which
+   --          has one of the two following forms:
 
    --            L file | line type col R      user entity
    --            L name-in-lower-case R        standard entity
@@ -196,13 +195,13 @@ package Lib.Xref is
    --              ^ = subprogram ACCESS parameter
 
    --           b is used for spec entities that are repeated in a body,
-   --           including the unit (subprogram, package, task, protected
-   --           body, protected entry) name itself, and in the case of a
-   --           subprogram, the formals. This letter is also used for the
-   --           occurrence of entry names in accept statements. Such entities
-   --           are not considered to be definitions for cross-referencing
-   --           purposes, but rather are considered to be references to the
-   --           corresponding spec entities, marked with this special type.
+   --           including the unit (subprogram, package, task, protected body,
+   --           protected entry) name itself, and in the case of a subprogram,
+   --           the formals. This letter is also used for the occurrence of
+   --           entry names in accept statements. Such entities are not
+   --           considered to be definitions for cross-referencing purposes,
+   --           but rather are considered to be references to the corresponding
+   --           spec entities, marked with this special type.
 
    --           c is similar to b but is used to mark the completion of a
    --           private or incomplete type. As with b, the completion is not
@@ -212,9 +211,9 @@ package Lib.Xref is
    --           d is used to identify a discriminant of a type. If this is
    --           an incomplete or private type with discriminants, the entry
    --           denotes the occurrence of the discriminant in the partial view
-   --           which is also the point of definition of the discriminant.
-   --           The occurrence of the same discriminant in the full view is
-   --           a regular reference to it.
+   --           which is also the point of definition of the discriminant. The
+   --           occurrence of the same discriminant in the full view is a
+   --           regular reference to it.
 
    --           e is used to identify the end of a construct in the following
    --           cases:
@@ -228,11 +227,11 @@ package Lib.Xref is
    --             Enumeration Definition );
 
    --           Note that 'e' entries are special in that they appear even
-   --           in referencing units (normally xref entries appear only
-   --           for references in the extended main source unit (see Lib) to
-   --           which the ali applies. But 'e' entries are really structural
-   --           and simply indicate where packages end. This information can
-   --           be used to reconstruct scope information for any entities
+   --           in referencing units (normally xref entries appear only for
+   --           references in the extended main source unit (see Lib) to which
+   --           the ali applies. But 'e' entries are really structural and
+   --           simply indicate where packages end. This information can be
+   --           used to reconstruct scope information for any entities
    --           referenced from within the package. The line/column values
    --           for these entries point to the semicolon ending the construct.
 
@@ -270,11 +269,10 @@ package Lib.Xref is
    --           entry in the section for the child duplicates this information
    --           but appears in the child rather than the parent.
 
-   --           l is used to identify the occurrence in the source of the
-   --           name on an end line. This is just a syntactic reference
-   --           which can be ignored for semantic purposes (such as call
-   --           graph construction). Again, in the case of an accept there
-   --           can be multiple l lines.
+   --           l is used to identify the occurrence in the source of the name
+   --           on an end line. This is just a syntactic reference which can be
+   --           ignored for semantic purposes (e.g. a call graph construction).
+   --           Again, in the case of an accept there can be multiple l lines.
 
    --           o is used for variables referenced from a SPARK 'own'
    --           definition. In the SPARK language, it is allowed to use a
@@ -315,14 +313,14 @@ package Lib.Xref is
    --           Note that in the case of accept statements, there can
    --           be multiple b and t entries for the same entity.
 
-   --           x is used to identify the reference as the entity from which
-   --           a tagged type is extended. This allows immediate access to
-   --           the parent of a tagged type.
+   --           x is used to identify the reference as the entity from which a
+   --           tagged type is extended. This allows immediate access to the
+   --           parent of a tagged type.
 
-   --           z is used on the cross-reference line for a generic unit, to
-   --           mark the definition of a generic formal of the unit.
-   --           This entry type is similar to 'k' and 'p' in that it is an
-   --           implicit reference for an entity with a different name.
+   --           z is used on the cross-reference line for a generic unit,
+   --           to mark the definition of a generic formal of the unit. This
+   --           entry type is similar to 'k' and 'p' in that it is an implicit
+   --           reference for an entity with a different name.
 
    --           The characters >, <. =, and ^ are used on the cross-reference
    --           line for a subprogram, to denote formal parameters and their
@@ -333,13 +331,12 @@ package Lib.Xref is
    --           references are present only if the entity in question is
    --           a generic entity, and in that case the [..] contains the
    --           reference for the instantiation. In the case of nested
-   --           instantiations, this can be nested [...[...[...]]] etc.
-   --           The reference is of the form [file|line] no column is
-   --           present since it is assumed that only one instantiation
-   --           appears on a single source line. Note that the appearance
-   --           of file numbers in such references follows the normal
-   --           rules (present only if needed, and resets the current
-   --           file for subsequent references).
+   --           instantiations, this can be nested [...[...[...]]] etc. The
+   --           reference is of the form [file|line] no column is present since
+   --           it is assumed that only one instantiation appears on a single
+   --           source line. Note that the appearance of file numbers in such
+   --           references follows the normal rules (present only if needed,
+   --           and resets the current file for subsequent references).
 
    --     Examples:
 
@@ -388,9 +385,9 @@ package Lib.Xref is
    --        10I3*Genv{integer} 3|4I10[6|12]
 
    --           This line gives a reference for the entity Genv in a generic
-   --           package. The reference in file 3, line 4, col 10, refers to
-   --           an instance of the generic where the instantiation can be
-   --           found in file 6 at line 12.
+   --           package. The reference in file 3, line 4, col 10, refers to an
+   --           instance of the generic where the instantiation can be found in
+   --           file 6 at line 12.
 
    --  Continuation lines are used if the reference list gets too long,
    --  a continuation line starts with a period, and then has references
@@ -410,26 +407,25 @@ package Lib.Xref is
    ----------------------------------------
 
    --  In the cross-reference section of the ali file, entity types are
-   --  identified by a single letter, indicating the entity type. The
-   --  following table indicates the letter. A space for an entry is
-   --  used for entities that do not appear in the cross-reference table.
-
-   --  For objects, the character * appears in this table. In the xref
-   --  listing, this character is replaced by the lower case letter that
-   --  corresponds to the type of the object. For example, if a variable
-   --  is of a Float type, then, since the type is represented by an
-   --  upper case F, the object would be represented by a lower case f.
-
-   --  A special exception is the case of booleans, whose entities are
-   --  normal E_Enumeration_Type or E_Enumeration_Subtype entities, but
-   --  which appear as B/b in the xref lines, rather than E/e.
-
-   --  For private types, the character + appears in the table. In this
-   --  case the kind of the underlying type is used, if available, to
-   --  determine the character to use in the xref listing. The listing
-   --  will still include a '+' for a generic private type, for example,
-   --  but will retain the '*' for an object or formal parameter of such
-   --  a type.
+   --  identified by a single letter, indicating the entity type. The following
+   --  table indicates the letter. A space for an entry is used for entities
+   --  that do not appear in the cross-reference table.
+
+   --  For objects, the character * appears in this table. In the xref listing,
+   --  this character is replaced by the lower case letter that corresponds to
+   --  the type of the object. For example, if a variable is of a Float type,
+   --  then, since the type is represented by an upper case F, the object would
+   --  be represented by a lower case f.
+
+   --  A special exception is the case of booleans, whose entities are normal
+   --  E_Enumeration_Type or E_Enumeration_Subtype entities, but which appear
+   --  as B/b in the xref lines, rather than E/e.
+
+   --  For private types, the character + appears in the table. In this case
+   --  the kind of the underlying type is used, if available, to determine the
+   --  character to use in the xref listing. The listing will still include a
+   --  '+' for a generic private type, for example, but will retain the '*' for
+   --  an object or formal parameter of such a type.
 
    --  For subprograms, the characters 'U' and 'V' appear in the table,
    --  indicating procedures and functions. If the operation is abstract,
@@ -525,11 +521,10 @@ package Lib.Xref is
       E_Return_Statement                           => ' ',
       E_Package                                    => 'K',
 
-      --  The following entities are not ones to which we gather
-      --  cross-references, since it does not make sense to do so
-      --  (e.g. references to a package are to the spec, not the body)
-      --  Indeed the occurrence of the body entity is considered to
-      --  be a reference to the spec entity.
+      --  The following entities are not ones to which we gather the cross-
+      --  references, since it does not make sense to do so (e.g. references to
+      --  a package are to the spec, not the body) Indeed the occurrence of the
+      --  body entity is considered to be a reference to the spec entity.
 
       E_Package_Body                               => ' ',
       E_Protected_Object                           => ' ',
@@ -537,8 +532,8 @@ package Lib.Xref is
       E_Task_Body                                  => ' ',
       E_Subprogram_Body                            => ' ');
 
-   --  The following table is for information purposes. It shows the
-   --  use of each character appearing as an entity type.
+   --  The following table is for information purposes. It shows the use of
+   --  each character appearing as an entity type.
 
    --  letter  lower case usage                UPPER CASE USAGE
 
@@ -701,18 +696,17 @@ package Lib.Xref is
    -- Handling of Imported Subprograms --
    --------------------------------------
 
-   --  If a pragma Import or Interface applies to a subprogram, the
-   --  pragma is the completion of the subprogram. This is noted in
-   --  the ALI file by making the occurrence of the subprogram in the
-   --  pragma into a body reference ('b') and by including the external
-   --  name of the subprogram and its language, bracketed by '<' and '>'
-   --  in that reference. For example:
+   --  If a pragma Import or Interface applies to a subprogram, the pragma is
+   --  the completion of the subprogram. This is noted in the ALI file by
+   --  making the occurrence of the subprogram in the pragma into a body
+   --  reference ('b') and by including the external name of the subprogram and
+   --  its language, bracketed by '<' and '>' in that reference. For example:
    --
    --     3U13*elsewhere 4b<c,there>21
    --
-   --  indicates that procedure elsewhere, declared at line 3, has a
-   --  pragma Import at line 4, that its body is in C, and that the link
-   --  name as given in the pragma is "there".
+   --  indicates that procedure elsewhere, declared at line 3, has a pragma
+   --  Import at line 4, that its body is in C, and that the link name as given
+   --  in the pragma is "there".
 
    -----------------
    -- Subprograms --
@@ -727,10 +721,10 @@ package Lib.Xref is
    --  Node N is an operator node, whose entity has been set. If this entity
    --  is a user defined operator (i.e. an operator not defined in package
    --  Standard), then a reference to the operator is recorded at node N.
-   --  T is the operand type of the operator. A reference to the operator
-   --  is an implicit reference to the type, and that needs to be recorded
-   --  to avoid spurious warnings on unused entities, when the operator is
-   --  a renaming of a predefined operator.
+   --  T is the operand type of the operator. A reference to the operator is an
+   --  implicit reference to the type, and that needs to be recorded to avoid
+   --  spurious warnings on unused entities, when the operator is a renaming of
+   --  a predefined operator.
 
    procedure Generate_Reference
      (E       : Entity_Id;
@@ -738,19 +732,19 @@ package Lib.Xref is
       Typ     : Character := 'r';
       Set_Ref : Boolean   := True;
       Force   : Boolean   := False);
-   --  This procedure is called to record a reference. N is the location
-   --  of the reference and E is the referenced entity. Typ is one of:
+   --  This procedure is called to record a reference. N is the location of the
+   --  reference and E is the referenced entity. Typ is one of:
    --
    --    a character already described in the description of ref entries above
    --    ' ' for dummy reference (see below)
    --
-   --  Note: all references to incomplete or private types are to the
-   --  original (incomplete or private type) declaration. The full
-   --  declaration is treated as a reference with type 'c'.
+   --  Note: all references to incomplete or private types are to the original
+   --  (incomplete or private type) declaration. The full declaration is
+   --  treated as a reference with type 'c'.
    --
-   --  Note: all references to packages or subprograms are to the entity
-   --  for the spec. The entity in the body is treated as a reference
-   --  with type 'b'. Similar handling for references to subprogram formals.
+   --  Note: all references to packages or subprograms are to the entity for
+   --  the spec. The entity in the body is treated as a reference with type
+   --  'b'. Similar handling for references to subprogram formals.
    --
    --  The call has no effect if N is not in the extended main source unit
    --  This check is omitted for type 'e' references (where it is useful to
diff --git a/gcc/ada/sem_ch3.adb b/gcc/ada/sem_ch3.adb
index d30d444..d99abef 100644
--- a/gcc/ada/sem_ch3.adb
+++ b/gcc/ada/sem_ch3.adb
@@ -3702,6 +3702,9 @@ package body Sem_Ch3 is
          Analyze_Aspect_Specifications (N, Id);
       end if;
 
+      --  Generate 'I' xref for object initialization at definition, only used
+      --  for the local xref section used in ALFA mode.
+
       if ALFA_Mode and then Present (Expression (Original_Node (N))) then
          Generate_Reference (Id, Id, 'I');
       end if;