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
