RFR: 8360037: Refactor ImageReader in preparation for Valhalla support [v16]

[David Beaumont]

On Thu, 31 Jul 2025 13:42:42 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> David Beaumont has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Convert non-visible markdown comments to JavaDoc for consistency.
>
> src/java.base/share/classes/jdk/internal/jimage/ImageReader.java line 283:
> 
>> 281:          *
>> 282:          * <p>Note also that there is no reentrant calling back to this method from within
>> 283:          * the node handling code.
> 
> This paragraph and the previous one feels like too much detail and I'm not sure they are necessary.

As someone who struggled through understanding this code, mainly do to sparse comments, I added additional information for the next maintainer. The no-reentrant calling behaviour is actually important to avoid issues during evaluation, and I tripped over this at least once (hence a comment). Happy to reframe it as "future changes shouldn't call back reentrantly" (as an instruction, not an observation).

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

PR Review Comment: https://git.openjdk.org/jdk/pull/26054#discussion_r2248004502