https://gcc.gnu.org/g:8577f2ebef69b4c6a15ca9db2a93acbb2eccb73f

commit r16-1310-g8577f2ebef69b4c6a15ca9db2a93acbb2eccb73f
Author: Ronan Desplanques <desplanq...@adacore.com>
Date:   Fri Feb 28 12:25:20 2025 +0100

    ada: Clarify warning in Atree.Rewrite documentation
    
    The documentation of Atree.Rewrite warns about a potential misuse of
    that subprogram. This patch makes the text of that warning more specific.
    The documentation of Atree.Replace had the same note but this patch
    replaces it with a mention of the one in Rewrite's documentation.
    
    gcc/ada/ChangeLog:
    
            * atree.ads (Rewrite, Replace): Clarify comments.

Diff:
---
 gcc/ada/atree.ads | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/gcc/ada/atree.ads b/gcc/ada/atree.ads
index 142616921421..760c63b9bea1 100644
--- a/gcc/ada/atree.ads
+++ b/gcc/ada/atree.ads
@@ -539,9 +539,10 @@ package Atree is
    --  newly constructed replacement subtree.
    --
    --  Note: New_Node may not contain references to Old_Node, for example as
-   --  descendants, since the rewrite would make such references invalid. If
-   --  New_Node does need to reference Old_Node, then these references should
-   --  be to a relocated copy of Old_Node (see Relocate_Node procedure).
+   --  descendants, since the rewrite would turn them into cyclic
+   --  self-references. If New_Node does need to reference Old_Node, then these
+   --  references should be to a relocated copy of Old_Node (see Relocate_Node
+   --  procedure).
    --
    --  Note: The Original_Node function applied to Old_Node (which has now
    --  been replaced by the contents of New_Node), can be used to obtain the
@@ -555,10 +556,8 @@ package Atree is
    --  original contents of the Old_Node, but rather the New_Node value.
    --  Replace also preserves the setting of Comes_From_Source.
    --
-   --  Note that New_Node must not contain references to Old_Node, for example
-   --  as descendants, since the rewrite would make such references invalid. If
-   --  New_Node does need to reference Old_Node, then these references should
-   --  be to a relocated copy of Old_Node (see Relocate_Node procedure).
+   --  The note in the documentation of Rewrite about the risk of creating
+   --  cyclic references also applies here.
    --
    --  Replace is used in certain circumstances where it is desirable to
    --  suppress any history of the rewriting operation. Notably, it is used

Reply via email to