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

[David Beaumont]

On Tue, 22 Jul 2025 15:29:57 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Absolutely. This sort of thing is always a balance between clarity and conciseness. But here I think you're right so I pulled the `name` into a `@param`. I dislike doing it for the return types in most cases though, since that encourages duplication with the method's first sentence.
>
> The {@return 1st sentence text} can be used on the first line and javadoc will put the text in both places without needing duplication in the source.  [(javadoc  tag specification](https://docs.oracle.com/en/java/javase/22/docs/specs/javadoc/doc-comment-spec.html))

I don't think that's better because the "1st sentence text" isn't prefixed with the word "Returns", one if a verb-phase (the action of the method) and the other a noun phrase (the thing returned).

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

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