changeset 205:229b1dadb202

Some basic Javadoc for new annotations.
author shade
date Wed, 13 Aug 2014 03:13:00 +0400
parents 7f77b1275a5b
children 8af457433465
files jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Expect.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressMeta.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressTest.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Outcome.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Ref.java
diffstat 5 files changed, 31 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Expect.java	Wed Aug 13 03:03:03 2014 +0400
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Expect.java	Wed Aug 13 03:13:00 2014 +0400
@@ -24,10 +24,33 @@
  */
 package org.openjdk.jcstress.annotations;
 
+/**
+ * Provides the grading for the {@link Outcome}.
+ */
 public enum Expect {
+
+    /**
+     * May be present as the valid result; may be absent if tests haven't been able to reach to that outcome.
+     */
     ACCEPTABLE,
+
+    /**
+     * Same as ACCEPTABLE, but this outcome will be highlighted in reports.
+     */
     ACCEPTABLE_INTERESTING,
+
+    /**
+     * Same as ACCEPTABLE, but only for outcomes which are formally acceptable, but may be surprising to end users.
+     */
     ACCEPTABLE_SPEC,
+
+    /**
+     * Should always be absent.
+     */
     FORBIDDEN,
+
+    /**
+     * Internal: no grading.
+     */
     UNKNOWN,
 }
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressMeta.java	Wed Aug 13 03:03:03 2014 +0400
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressMeta.java	Wed Aug 13 03:13:00 2014 +0400
@@ -30,7 +30,11 @@
 import java.lang.annotation.Target;
 
 /**
+ * Points to another class with test meta-information.
  *
+ * <p>When placed over {@link JCStressTest} class, the {@link Description}, {@link Outcome},
+ * {@link Ref}, and other annotations will be inherited from the pointed class. This allows
+ * to declare the description, grading and references only once for a group of tests.</p>
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressTest.java	Wed Aug 13 03:03:03 2014 +0400
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressTest.java	Wed Aug 13 03:13:00 2014 +0400
@@ -35,6 +35,8 @@
  * {@link Actor} and {@link Arbiter} annotations are used to describe test
  * behavior. {@link State} and {@link Result} annotations are used to
  * describe the test state.
+ * <p/>
+ * The grading for test is done with {@link Outcome} annotations.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Outcome.java	Wed Aug 13 03:03:03 2014 +0400
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Outcome.java	Wed Aug 13 03:13:00 2014 +0400
@@ -34,7 +34,7 @@
 /**
  * Describes the test outcome.
  *
- * <p>Multiple cases with distinct states can be provided for a given test.</p>
+ * <p>Multiple outcomes with distinct IDs can be provided.</p>
  */
 @Inherited
 @Target(ElementType.TYPE)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Ref.java	Wed Aug 13 03:03:03 2014 +0400
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Ref.java	Wed Aug 13 03:13:00 2014 +0400
@@ -32,7 +32,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Reference element.
+ * Provides the external reference for the test case (URL, BibTeX, ISBN, etc.)
  */
 @Inherited
 @Target(ElementType.TYPE)