RFR: 8367531: Template Framework: use scopes and tokens instead of misbehaving immediate-return-queries [v4]

[Emanuel Peter]

On Tue, 14 Oct 2025 15:06:00 GMT, Manuel Hässig <mhaessig at openjdk.org> wrote:

>> Emanuel Peter has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   fix TestMethodArguments.java after merge with master
>
> test/hotspot/jtreg/testlibrary_tests/template_framework/examples/TestTutorial.java line 469:
> 
>> 467:     // the top of the class, and insert a field.
>> 468:     //
>> 469:     // The choice of transparency of an insertion scope is quite important. A common use case
> 
> What is an "insertion scope"?

I extended the comment: `insertion scope (the scope that is inserted)`.
I also add a definition of 3 relevant scopes:


   472     // In this example, we look at the use of Hooks. They allow us to reach back, to outer
   473     // scopes. For example, we can reach out from inside a method body to a hook anchored at
   474     // the top of the class, and insert a field.
   475     //
~  476     // When we insert to a hook, we have 3 relevant scopes:
~  477     // - Anchor scope: the scope defined at "hook.anchor(scope(...))"
+  478     // - Insertion scope: the scope that is inserted, see "hook.insert(scope(...))"   
+  479     // - Caller scope: the scope we insert from.                                                                                                                                                              
+  480     //
+  481     // The choice of transparency of an insertion scope (the scope that is inserted) is quite
+  482     // important. A common use case is to insert a DataName.
   483     // See: generateWithDataNamesForFieldsAndVariables
   484     // See: generateWithScopes1

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27255#discussion_r2429760095