ada: Improve documentation comment of Find_Type_Name

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.

diff --git a/gcc/ada/sem_ch3.ads b/gcc/ada/sem_ch3.ads
index 0880dac0421248b57f2a60b5ff6180786e927a64..0c2e66f293b3eef8a11756776e268778b6d5b44b 100644 (file)
--- 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;