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