[gcc r12-592] [Ada] Remove some ??? comments

[gcc r12-592] [Ada] Remove some ??? comments

[Pierre-Marie de Rodat]

https://gcc.gnu.org/g:62acd2c453976165d2a6cd48d06a7341408b7e78

commit r12-592-g62acd2c453976165d2a6cd48d06a7341408b7e78
Author: Gary Dismukes <dismukes@adacore.com>
Date:   Fri Jan 29 20:03:34 2021 -0500

    [Ada] Remove some ??? comments
    
    gcc/ada/
    
            * errout.ads (Size_Too_Small_Message): Remove low-value ???
            comment.
            * exp_util.ads: Remove ??? in part of overall package comments
            and restructure comment to clarify.
            (Duplicate_Subexpr): Remove ??? comment that seems unnecessary.
            * sem_ch3.ads (Analyze_Declarations): Remove two parenthesized
            ??? comments and add more description of the procedure's
            actions.
            (Get_Discriminant_Value): Remove ??? comment requesting more
            documentation, expanding description of the function's actions.
            * sem_disp.ads (Check_Operation_From_Incomplete_Type): Add more
            semantic description of the procedure and remove ??? comment
            requesting such.
            (Propagate_Tag): Refine comment to indicate meaning of formal
            parameters and generally improve the spec comment (and remove
            ??? comment asking about the parameters).

Diff:
---
 gcc/ada/errout.ads   |  6 +++---
 gcc/ada/exp_util.ads | 12 ++++++------
 gcc/ada/sem_ch3.ads  | 13 ++++++++-----
 gcc/ada/sem_disp.ads | 25 ++++++++++++++-----------
 4 files changed, 31 insertions(+), 25 deletions(-)

diff --git a/gcc/ada/errout.ads b/gcc/ada/errout.ads
index 6316cf44590..baec3a74b91 100644
--- a/gcc/ada/errout.ads
+++ b/gcc/ada/errout.ads
@@ -1006,8 +1006,8 @@ package Errout is
    Size_Too_Small_Message : constant String :=
      "size for& too small, minimum allowed is ^";
    --  This message is printed in Freeze and Sem_Ch13. We also test for it in
-   --  the body of this package (see Special_Msg_Delete) ???which is somewhat
-   --  questionable. The Is_Size_Too_Small_Message function tests for it by
-   --  testing a prefix. The function and constant should be kept in synch.
+   --  the body of this package (see Special_Msg_Delete).
+   --  Function Is_Size_Too_Small_Message tests for it by testing a prefix.
+   --  The function and constant should be kept in synch.
 
 end Errout;
diff --git a/gcc/ada/exp_util.ads b/gcc/ada/exp_util.ads
index e68290ff362..7f1a93222d5 100644
--- a/gcc/ada/exp_util.ads
+++ b/gcc/ada/exp_util.ads
@@ -50,11 +50,11 @@ package Exp_Util is
    --    of statements, the actions are simply inserted into the list before
    --    the associated statement.
 
-   --    For an expression occurring in a declaration (declarations always
-   --    appear in lists), the actions are similarly inserted into the list
-   --    just before the associated declaration. ???Declarations do not always
-   --    appear in lists; in particular, a library unit declaration does not
-   --    appear in a list, and Insert_Action will crash in that case.
+   --    For an expression occurring in a declaration the actions are similarly
+   --    inserted into the list just before the associated declaration. (But
+   --    note that although declarations usually appear in lists, they don't
+   --    always; in particular, a library unit declaration does not appear in
+   --    a list, and Insert_Action will crash in that case.)
 
    --  The following special cases arise:
 
@@ -477,7 +477,7 @@ package Exp_Util is
    --
    --  The Name_Req flag is set to ensure that the result is suitable for use
    --  in a context requiring a name (for example, the prefix of an attribute
-   --  reference) (can't this just be a qualification in Ada 2012???).
+   --  reference).
    --
    --  The Renaming_Req flag is set to produce an object renaming declaration
    --  rather than an object declaration. This is valid only if the expression
diff --git a/gcc/ada/sem_ch3.ads b/gcc/ada/sem_ch3.ads
index 0299e054a2e..dcd4a348852 100644
--- a/gcc/ada/sem_ch3.ads
+++ b/gcc/ada/sem_ch3.ads
@@ -69,8 +69,10 @@ package Sem_Ch3 is
    --  interface primitives with the tagged type primitives that cover them.
 
    procedure Analyze_Declarations (L : List_Id);
-   --  Called to analyze a list of declarations (in what context ???). Also
-   --  performs necessary freezing actions (more description needed ???)
+   --  Called to analyze a list of declarations. Also performs necessary
+   --  freezing actions (such as freezing remaining unfrozen entities at
+   --  the end of declarative parts), resolves usage names in aspects, and
+   --  analyzes contracts that require delay until after freezing is done.
 
    procedure Analyze_Interface_Declaration (T : Entity_Id; Def : Node_Id);
    --  Analyze an interface declaration or a formal interface declaration
@@ -169,9 +171,10 @@ package Sem_Ch3 is
      (Discriminant       : Entity_Id;
       Typ_For_Constraint : Entity_Id;
       Constraint         : Elist_Id) return Node_Id;
-   --  ??? MORE DOCUMENTATION
-   --  Given a discriminant somewhere in the Typ_For_Constraint tree and a
-   --  Constraint, return the value of that discriminant.
+   --  Given a discriminant Discriminant occurring somewhere up the derivation
+   --  tree from Typ_For_Constraint and a Constraint, return the expression
+   --  corresponding to that discriminant in the constraint that specifies its
+   --  value.
 
    function Is_Null_Extension (T : Entity_Id) return Boolean;
    --  Returns True if the tagged type T has an N_Full_Type_Declaration that
diff --git a/gcc/ada/sem_disp.ads b/gcc/ada/sem_disp.ads
index d0f22952517..c9aa3667ac7 100644
--- a/gcc/ada/sem_disp.ads
+++ b/gcc/ada/sem_disp.ads
@@ -57,11 +57,15 @@ package Sem_Disp is
    procedure Check_Operation_From_Incomplete_Type
      (Subp : Entity_Id;
       Typ  : Entity_Id);
-   --  If a primitive operation was defined for the incomplete view of the
-   --  type, and the full type declaration is a derived type definition,
-   --  the operation may override an inherited one.
-   --  Need more description here, what are the parameters, and what does
-   --  this call actually do???
+   --  If a primitive subprogram Subp was defined for the incomplete view of
+   --  Typ, and the full type declaration is a derived type, then Subp may
+   --  override a subprogram inherited from the parent type. In that case,
+   --  the inherited subprogram will have been hidden by the current one at
+   --  the point of the type derivation, so it does not appear in the list
+   --  of primitive operations of the type, and this procedure inserts the
+   --  overriding subprogram in the the full type's list of primitives by
+   --  iterating over the list for the parent type. If instead Subp is a new
+   --  primitive, then it's simply appended to the primitive list.
 
    procedure Check_Operation_From_Private_View (Subp, Old_Subp : Entity_Id);
    --  No action performed if Subp is not an alias of a dispatching operation.
@@ -172,11 +176,10 @@ package Sem_Disp is
    --  function. The caller checks that Tagged_Type is indeed a tagged type.
 
    procedure Propagate_Tag (Control : Node_Id; Actual : Node_Id);
-   --  If a function call is tag-indeterminate, its controlling argument is
-   --  found in the context: either an enclosing call, or the left-hand side
-   --  of the enclosing assignment statement. The tag must be propagated
-   --  recursively to the tag-indeterminate actuals of the call.
-   --  Need clear description of the parameters Control and Actual, especially
-   --  since the comments above refer to actuals in the plural ???
+   --  If a function call given by Actual is tag-indeterminate, its controlling
+   --  argument is found in the context, given by Control: either from an
+   --  operand of an enclosing call, or the left-hand side of the enclosing
+   --  assignment statement. The tag of Control will be propagated recursively
+   --  to Actual and to its tag-indeterminate operands, if any.
 
 end Sem_Disp;