changeset 902:7811fb328a4c

Clean up JMH annotations Javadocs.
author shade
date Fri, 11 Jul 2014 10:45:30 +0400
parents 16caa87c4b0d
children 2e167775cc75
files jmh-core/src/main/java/org/openjdk/jmh/annotations/AuxCounters.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Benchmark.java jmh-core/src/main/java/org/openjdk/jmh/annotations/BenchmarkMode.java jmh-core/src/main/java/org/openjdk/jmh/annotations/CompilerControl.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Fork.java jmh-core/src/main/java/org/openjdk/jmh/annotations/GroupThreads.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Level.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Measurement.java jmh-core/src/main/java/org/openjdk/jmh/annotations/OperationsPerInvocation.java jmh-core/src/main/java/org/openjdk/jmh/annotations/OutputTimeUnit.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Scope.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Setup.java jmh-core/src/main/java/org/openjdk/jmh/annotations/State.java jmh-core/src/main/java/org/openjdk/jmh/annotations/TearDown.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Threads.java jmh-core/src/main/java/org/openjdk/jmh/annotations/Warmup.java
diffstat 16 files changed, 77 insertions(+), 91 deletions(-) [+]
line wrap: on
line diff
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/AuxCounters.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/AuxCounters.java	Fri Jul 11 10:45:30 2014 +0400
@@ -30,11 +30,11 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>{@link org.openjdk.jmh.annotations.AuxCounters} annotation can be used to mark
- * {@link State} objects as the bearers of auxiliary secondary results. Marking the
- * class with this annotation will enable JMH to look for public {int, long} fields,
- * as well as public methods returning {int, long} values, and treat their values as
- * the operation counts in current iteration.</p>
+ * <p>{@link AuxCounters} annotation can be used to mark {@link State} objects
+ * as the bearers of auxiliary secondary results. Marking the class with this annotation
+ * will enable JMH to look for public {int, long} fields, as well as public methods
+ * returning {int, long} values, and treat their values as the operation counts
+ * in current iteration.</p>
  *
  * <p><b>THIS IS AN EXPERIMENTAL API, which means, among other things:</b></p>
  *
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Benchmark.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Benchmark.java	Fri Jul 11 10:45:30 2014 +0400
@@ -42,22 +42,21 @@
  * look through
  * <a href="http://hg.openjdk.java.net/code-tools/jmh/file/tip/jmh-samples/src/main/java/org/openjdk/jmh/samples/">
  * JMH samples</a> for their canonical uses. As the rule of thumb, most annotations
- * may be placed either at the {@link Benchmark} method, or at enclosing
- * class.</p>
+ * may be placed either at the {@link Benchmark} method, or at enclosing class.</p>
  *
- * <p>{@link Benchmark} demarcates the benchmark payload,
- * and JMH treats it specifically as the wrapper which contains the benchmark code. In order to
- * run the benchmark reliably, JMH enforces a few stringent properties for these wrapper methods,
- * including, but not limited to:</p>
+ * <p>{@link Benchmark} demarcates the benchmark payload, and JMH treats it specifically
+ * as the wrapper which contains the benchmark code. In order to run the benchmark reliably,
+ * JMH enforces a few stringent properties for these wrapper methods, including, but not
+ * limited to:</p>
  * <ul>
  *     <li>Method should be public</li>
- *     <li>Arguments may only include either {@link org.openjdk.jmh.annotations.State} classes, which
- *     JMH will inject while calling the method (see {@link org.openjdk.jmh.annotations.State} for
- *     more details), or JMH infrastructure classes, like {@link org.openjdk.jmh.infra.Control},
- *     or {@link org.openjdk.jmh.infra.Blackhole}</li>
- *     <li>Method can only be synchronized if a relevant {@link org.openjdk.jmh.annotations.State} is placed
+ *     <li>Arguments may only include either {@link State} classes, which JMH will inject
+ *     while calling the method (see {@link State} for more details), or JMH infrastructure
+ *     classes, like {@link org.openjdk.jmh.infra.Control}, or {@link org.openjdk.jmh.infra.Blackhole}</li>
+ *     <li>Method can only be synchronized if a relevant {@link State} is placed
  *     on the enclosing class.</li>
  * </ul>
+ *
  * <p>If you want to benchmark methods which break these properties, you have to write them
  * out specifically as the benchmark payload and call them from {@link Benchmark}
  * method.</p>
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/BenchmarkMode.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/BenchmarkMode.java	Fri Jul 11 10:45:30 2014 +0400
@@ -32,13 +32,12 @@
 
 /**
  * <p>Benchmark mode declares the default modes in which this benchmark
- * would run. See {@link org.openjdk.jmh.annotations.Mode} for available
- * benchmark modes.</p>
+ * would run. See {@link Mode} for available benchmark modes.</p>
  *
- * <p>This annotation may be put at {@link Benchmark}
- * method to have effect on that method only, or at the enclosing class instance
- * to have the effect over all {@link Benchmark} methods
- * in the class. This annotation may be overridden with the runtime options.</p>
+ * <p>This annotation may be put at {@link Benchmark} method to have effect
+ * on that method only, or at the enclosing class instance to have the effect
+ * over all {@link Benchmark} methods in the class. This annotation may be
+ * overridden with the runtime options.</p>
  */
 @Inherited
 @Target({ElementType.METHOD, ElementType.TYPE})
@@ -47,7 +46,7 @@
 
     /**
      * @return Which benchmark modes to use.
-     * @see org.openjdk.jmh.annotations.Mode
+     * @see Mode
      */
     Mode[] value();
 
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/CompilerControl.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/CompilerControl.java	Fri Jul 11 10:45:30 2014 +0400
@@ -33,7 +33,7 @@
  * <p>Compiler control annotation may be used to affect the compilation of
  * particular methods in the benchmarks.</p>
  *
- * <p>JMH interfaces with the JVM by the means of command-line switches,
+ * <p>JMH interfaces with the JVM by the means of CompilerCommand interface,
  * These annotations only work with forking enabled. Non-forked runs will not be
  * able to pass the hints to the compiler. Also, these control annotations might
  * get freely ignored by the compiler, reduced to no-ops, or otherwise invalidated.
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Fork.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Fork.java	Fri Jul 11 10:45:30 2014 +0400
@@ -33,12 +33,10 @@
 /**
  * Fork annotation allows to set the default forking parameters for the benchmark.
  *
- * <p>
- * This annotation may be put at {@link Benchmark}
- * method to have effect on that method only, or at the enclosing class instance
- * to have the effect over all {@link Benchmark} methods
- * in the class. This annotation may be overridden with the runtime options.
- * </p>
+ * <p>This annotation may be put at {@link Benchmark} method to have effect on that
+ * method only, or at the enclosing class instance to have the effect over all
+ * {@link Benchmark} methods in the class. This annotation may be overridden with
+ * the runtime options.</p>
  */
 @Inherited
 @Target({ElementType.METHOD,ElementType.TYPE})
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/GroupThreads.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/GroupThreads.java	Fri Jul 11 10:45:30 2014 +0400
@@ -31,19 +31,16 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>
- * GroupThreads defines how many threads are participating in running
- * a particular {@link Benchmark} method in the group.
- * </p>
- * <p>
- * <b>Interaction with "total threads" settings:</b> JMH will always have the full
+ * <p>GroupThreads defines how many threads are participating in running
+ * a particular {@link Benchmark} method in the group.</p>
+ *
+ * <p><b>Interaction with "total threads" settings:</b> JMH will always have the full
  * execution groups, which forces the framework to round up the total number of threads
- * to accommodate the execution group size. For example, running {@link org.openjdk.jmh.annotations.Group}
- * with two {@link Benchmark} methods, each having
- * {@link GroupThreads}(4), will run 8*N threads (where N is integer), regardless of
- * the requested total number of threads.
- * </p>
- * @see org.openjdk.jmh.annotations.Group
+ * to accommodate the execution group size. For example, running {@link Group}
+ * with two {@link Benchmark} methods, each having {@link GroupThreads}(4), will run
+ * 8*N threads (where N is integer), regardless of the requested total number of threads.</p>
+ *
+ * @see Group
  */
 @Inherited
 @Target({ElementType.METHOD})
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Level.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Level.java	Fri Jul 11 10:45:30 2014 +0400
@@ -27,7 +27,7 @@
 /**
  * Control when to run the fixture methods.
  *
- * @see org.openjdk.jmh.annotations.Setup
+ * @see Setup
  * @see TearDown
  */
 public enum Level {
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Measurement.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Measurement.java	Fri Jul 11 10:45:30 2014 +0400
@@ -35,12 +35,12 @@
  * <p>Measurement annotations allows to set the default measurement parameters for
  * the benchmark.</p>
  *
- * <p>This annotation may be put at {@link Benchmark}
- * method to have effect on that method only, or at the enclosing class instance
- * to have the effect over all {@link Benchmark} methods
- * in the class. This annotation may be overridden with the runtime options.</p>
+ * <p>This annotation may be put at {@link Benchmark} method to have effect on that
+ * method only, or at the enclosing class instance to have the effect over all
+ * {@link Benchmark} methods in the class. This annotation may be overridden with
+ * the runtime options.</p>
  *
- * @see org.openjdk.jmh.annotations.Warmup
+ * @see Warmup
  */
 @Inherited
 @Target({ElementType.METHOD,ElementType.TYPE})
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/OperationsPerInvocation.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/OperationsPerInvocation.java	Fri Jul 11 10:45:30 2014 +0400
@@ -47,10 +47,9 @@
  * }
  * </pre></blockquote>
  *
- * <p>This annotation may be put at {@link Benchmark}
- * method to have effect on that method only, or at the enclosing class instance
- * to have the effect over all {@link Benchmark} methods
- * in the class.</p>
+ * <p>This annotation may be put at {@link Benchmark} method to have effect on that method
+ * only, or at the enclosing class instance to have the effect over all {@link Benchmark}
+ * methods in the class.</p>
  */
 @Inherited
 @Target({ElementType.METHOD,ElementType.TYPE})
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/OutputTimeUnit.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/OutputTimeUnit.java	Fri Jul 11 10:45:30 2014 +0400
@@ -34,10 +34,10 @@
 /**
  * <p>OutputTimeUnit provides the default time unit to report the results in.</p>
  *
- * <p>This annotation may be put at {@link Benchmark}
- * method to have effect on that method only, or at the enclosing class instance
- * to have the effect over all {@link Benchmark} methods
- * in the class. This annotation may be overridden with the runtime options.</p>
+ * <p>This annotation may be put at {@link Benchmark} method to have effect on that
+ * method only, or at the enclosing class instance to have the effect over all
+ * {@link Benchmark} methods in the class. This annotation may be overridden with
+ * the runtime options.</p>
  */
 @Inherited
 @Target({ElementType.METHOD,ElementType.TYPE})
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Scope.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Scope.java	Fri Jul 11 10:45:30 2014 +0400
@@ -25,7 +25,7 @@
 package org.openjdk.jmh.annotations;
 
 /**
- * {@link org.openjdk.jmh.annotations.State} scope.
+ * {@link State} scope.
  */
 public enum Scope {
 
@@ -36,7 +36,7 @@
      * worker threads.</p>
      *
      * <p>{@link Setup} and {@link TearDown} methods on this state object would be performed
-     * by one of the worker threads, and only once per {@link org.openjdk.jmh.annotations.Level}.
+     * by one of the worker threads, and only once per {@link Level}.
      * No other threads would ever touch the state object.</p>
      */
     Benchmark,
@@ -49,7 +49,7 @@
      * state object.</p>
      *
      * <p>{@link Setup} and {@link TearDown} methods on this state object would be performed
-     * by one of the group threads, and only once per {@link org.openjdk.jmh.annotations.Level}.
+     * by one of the group threads, and only once per {@link Level}.
      * No other threads would ever touch the state object.</p>
      *
      * @see Group
@@ -63,7 +63,7 @@
      * state objects are injected in the same benchmark</p>
      *
      * <p>{@link Setup} and {@link TearDown} methods on this state object would be performed
-     * by single worker thread exclusively, and only once per {@link org.openjdk.jmh.annotations.Level}.
+     * by single worker thread exclusively, and only once per {@link Level}.
      * No other threads would ever touch the state object.</p>
      *
      */
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Setup.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Setup.java	Fri Jul 11 10:45:30 2014 +0400
@@ -34,10 +34,9 @@
  *
  * <p>In order to figure out which thread should call the fixture, and what
  * state this method can initialize, {@link Setup} methods can only be declared in
- * {@link State} classes. Use {@link org.openjdk.jmh.annotations.Level} to decide
- * when to run the fixture.</p>
+ * {@link State} classes. Use {@link Level} to decide when to run the fixture.</p>
  *
- * @see org.openjdk.jmh.annotations.State
+ * @see State
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
@@ -45,7 +44,7 @@
 
     /**
      * @return Level of this method.
-     * @see org.openjdk.jmh.annotations.Level
+     * @see Level
      */
     Level value() default Level.Trial;
 
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/State.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/State.java	Fri Jul 11 10:45:30 2014 +0400
@@ -34,16 +34,16 @@
  * <p>Marks the state object.</p>
  *
  * <p>State objects naturally encapsulate the state on which benchmark is working on.
- * The {@link org.openjdk.jmh.annotations.Scope} of state object defines to which extent
- * it is shared among the worker threads.</p>
+ * The {@link Scope} of state object defines to which extent it is shared among the
+ * worker threads.</p>
  *
- * <p>State objects are usually injected into {@link Benchmark}
- * methods as arguments, and JMH takes care of their instantiation and sharing. State objects
- * may also be injected into {@link org.openjdk.jmh.annotations.Setup} and {@link org.openjdk.jmh.annotations.TearDown}
- * methods of other {@link org.openjdk.jmh.annotations.State} objects to get staged initialization.</p>
+ * <p>State objects are usually injected into {@link Benchmark} methods as arguments,
+ * and JMH takes care of their instantiation and sharing. State objects* may also be
+ * injected into {@link Setup} and {@link TearDown} methods of other {@link State}
+ * objects to get staged initialization.</p>
  *
- * <p>State objects may be inherited: you can place {@link org.openjdk.jmh.annotations.State}
- * on a super class and use subclasses as states.</p>
+ * <p>State objects may be inherited: you can place {@link State} on a super class and
+ * use subclasses as states.</p>
  */
 @Inherited
 @Target(ElementType.TYPE)
@@ -53,7 +53,7 @@
     /**
      * State scope.
      * @return state scope
-     * @see org.openjdk.jmh.annotations.Scope
+     * @see Scope
      */
     Scope value();
 
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/TearDown.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/TearDown.java	Fri Jul 11 10:45:30 2014 +0400
@@ -34,10 +34,9 @@
  *
  * <p>In order to figure out which thread should call the fixture, and what
  * state this method can initialize, {@link TearDown} methods can only be declared in
- * {@link State} classes. Use {@link org.openjdk.jmh.annotations.Level} to decide
- * when to run the fixture.</p>
+ * {@link State} classes. Use {@link Level} to decide when to run the fixture.</p>
  *
- * @see org.openjdk.jmh.annotations.State
+ * @see State
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
@@ -45,7 +44,7 @@
 
     /**
      * @return At which level to run this fixture.
-     * @see org.openjdk.jmh.annotations.Level
+     * @see Level
      */
     Level value() default Level.Trial;
 
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Threads.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Threads.java	Fri Jul 11 10:45:30 2014 +0400
@@ -33,10 +33,10 @@
 /**
  * <p>Threads annotation provides the default number of threads to run.</p>
  *
- * <p>This annotation may be put at {@link Benchmark}
- * method to have effect on that method only, or at the enclosing class instance
- * to have the effect over all {@link Benchmark} methods
- * in the class. This annotation may be overridden with the runtime options.</p>
+ * <p>This annotation may be put at {@link Benchmark} method to have effect
+ * on that method only, or at the enclosing class instance to have the effect
+ * over all {@link Benchmark} methods in the class. This annotation may be
+ * overridden with the runtime options.</p>
  */
 @Inherited
 @Target({ElementType.METHOD,ElementType.TYPE})
--- a/jmh-core/src/main/java/org/openjdk/jmh/annotations/Warmup.java	Wed Jul 09 18:56:08 2014 +0400
+++ b/jmh-core/src/main/java/org/openjdk/jmh/annotations/Warmup.java	Fri Jul 11 10:45:30 2014 +0400
@@ -32,17 +32,13 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * <p>
- * Warmup annotation allows to set the default warmup parameters for the benchmark.
- * </p>
- * <p>
- * This annotation may be put at {@link Benchmark}
- * method to have effect on that method only, or at the enclosing class instance
- * to have the effect over all {@link Benchmark} methods
- * in the class. This annotation may be overridden with the runtime options.
- * </p>
+ * <p>Warmup annotation allows to set the default warmup parameters for the benchmark.</p>
  *
- * @see org.openjdk.jmh.annotations.Measurement
+ * <p>This annotation may be put at {@link Benchmark} method to have effect on that method
+ * only, or at the enclosing class instance to have the effect over all {@link Benchmark}
+ * methods in the class. This annotation may be overridden with the runtime options.</p>
+ *
+ * @see Measurement
  */
 @Target({ElementType.METHOD,ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)