From: Ronan Desplanques <desplanq...@adacore.com>
The meaning of the return value of Find_Type_Name depends greatly on
whether the declaration it's passed is a completion. This patch adds a
description of this to the documentation comment of Find_Type_Name.
gcc/ada/ChangeLog:
* sem_ch3.ads (Find_Type_Name): Improve documentation comment.
Tested on x86_64-pc-linux-gnu, committed on master.
---
gcc/ada/sem_ch3.ads | 25 +++++++++++++++++++------
1 file changed, 19 insertions(+), 6 deletions(-)
diff --git a/gcc/ada/sem_ch3.ads b/gcc/ada/sem_ch3.ads
index 0880dac04212..0c2e66f293b3 100644
--- a/gcc/ada/sem_ch3.ads
+++ b/gcc/ada/sem_ch3.ads
@@ -165,12 +165,25 @@ package Sem_Ch3 is
-- node or a plain N_Identifier), find the type of the subtype mark.
function Find_Type_Name (N : Node_Id) return Entity_Id;
- -- Enter the identifier in a type definition, or find the entity already
- -- declared, in the case of the full declaration of an incomplete or
- -- private type. If the previous declaration is tagged then the class-wide
- -- entity is propagated to the identifier to prevent multiple incompatible
- -- class-wide types that may be created for self-referential anonymous
- -- access components.
+ -- N must be a type declaration. The declared view can be incomplete,
+ -- partial, or full. The behavior of this function depends on what
+ -- declaration, if there is one, N completes:
+ --
+ -- - If N is not a completion, the function enters the entity of N in the
+ -- name table and returns that entity.
+ -- - If N completes an incomplete view, the function sets the entity of N
+ -- as the full view of the incomplete view and returns the incomplete
+ -- view.
+ -- - If N completes a partial view, the function "swaps" the partial view
+ -- and the full view (see Copy_And_Swap) and returns the Entity_Id that,
+ -- on exit, points to the full view. The value that
+ -- Defining_Identifier (N) had on entry points to the partial view on
+ -- exit.
+ --
+ -- If the previous declaration is tagged then the class-wide entity is
+ -- propagated to the identifier to prevent multiple incompatible class-wide
+ -- types that may be created for self-referential anonymous access
+ -- components.
function Get_Discriminant_Value
(Discriminant : Entity_Id;
--
2.43.0
