RFR: 8346107: Generators: testing utility for random value generation

[Theo Weidmann]

On Tue, 7 Jan 2025 13:17:00 GMT, Emanuel Peter <epeter at openjdk.org> wrote:

>> This PR is a refactoring and partial rewrite of https://github.com/openjdk/jdk/pull/22716 by @eme64. The goals remain the same:
>> 
>>> For verification testing, it is often critical to generate "interesting" values, to provoke overflows, NaN, etc. And to generate these values in the correct distribution to trigger certain optimizations.
>>> 
>>> I would like to start a collection of such generators, that can then be used in testing.
>>> 
>>> The goal is to grow this collection in the future, and add new types. For example byte, char, short, or even Float16.
>>> 
>>> This will be helpful for the Template framework [JDK-8344942](https://bugs.openjdk.org/browse/JDK-8344942), but also other tests.
>>> 
>>> Related PR, for value verification: https://github.com/openjdk/jdk/pull/22715
>> 
>> The refactoring makes use of generics, rendering the generators library more flexible by default, by allowing it work with arbitrary types (with special features for Comparable types), improving the composability of different generators and streamlining the client API for simplicity. This allows test authors to quickly compose their own distributions and generators if necessary. An overview of this functionality is provided in the `Generators` javadoc.
>
> test/hotspot/jtreg/compiler/lib/generators/Generator.java line 33:
> 
>> 31:      * Returns the next value from the stream.
>> 32:      */
>> 33:     T next();
> 
> Should this not have a `@return`?
> 
> Why don't you run something like:
> `/oracle-work/jdk-fork0/build/linux-x64-debug/jdk/bin/javadoc -sourcepath test/hotspot/jtreg:./test/lib compiler.lib.generators`
> And make sure you don't have any errors/warnings :)

What would you like to see here with @return? I don't think there's any more information I can provide? Do you think the entire doc comment should be like below? In my experience that can be detrimental for some IDEs as they will only show the main text (for a lack of a better word) in some circumstances.

 ```
   /**
     * @returns the next value from the stream.
     */


To get away with all the warnings would mean documenting every single parameter everywhere (all lo's and hi's). Do you think that's really necessary?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/22941#discussion_r1905662756