From 62acd2c453976165d2a6cd48d06a7341408b7e78 Mon Sep 17 00:00:00 2001 From: Gary Dismukes Date: Fri, 29 Jan 2021 20:03:34 -0500 Subject: [PATCH] [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). --- 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 6316cf4..baec3a7 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 e68290f..7f1a932 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 0299e05..dcd4a34 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 d0f2295..c9aa366 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; -- 2.7.4