Documentation

docs/pages/pmd/devdocs/metrics_howto.md

@@ -72,10 +72,15 @@ public Object visit(ASTMethodDeclaration node, Object data) {
 }
 ```
 
-### Metric versions
+### Metric options
+
+Some metrics define options that can be used to slightly modify the computation. You'll typically see these options 
+gathered inside an enum in the implementation class of the metric, for example `CycloMetric.CycloOptions`. They're 
+also documented on the [index of metrics](/pmd_java_metrics_index.html).
+
+To use options with a metric, you must first bundle them into a `MetricOptions`. 
+
 
-{%include important.html content="Metric versions are about to be revamped into options that can be combined 
-together." %}
 
 
 ### Result options

pmd-apex/src/test/java/net/sourceforge/pmd/lang/apex/metrics/impl/AbstractApexMetricTestRule.java

@@ -95,9 +95,9 @@ public abstract class AbstractApexMetricTestRule extends AbstractApexRule {
 
 
     /**
-     * Mappings of labels to versions for use in the version property.
+     * Mappings of labels to options for use in the options property.
      *
-     * @return A map of labels to versions
+     * @return A map of labels to options
      */
     protected Map<String, MetricOption> optionMappings() {
         return new HashMap<>();

pmd-core/src/main/java/net/sourceforge/pmd/lang/metrics/MetricMemoizer.java

@@ -18,9 +18,9 @@ public interface MetricMemoizer<N extends Node> {
 
 
     /**
-     * Fetch a memoized result for a metric and version.
+     * Fetch a memoized result for a metric and options.
      *
-     * @param key The metric key parameterized with its version
+     * @param key The metric key parameterized with its options
      *
      * @return The memoized result, or null if it wasn't found
      */
@@ -28,9 +28,9 @@ public interface MetricMemoizer<N extends Node> {
 
 
     /**
-     * Memoizes a result for a metric and version.
+     * Memoizes a result for a metric and options.
      *
-     * @param key   The metric key parameterized with its version
+     * @param key   The metric key parameterized with its options
      * @param value The value to store
      */
     void memoize(ParameterizedMetricKey<N> key, double value);

pmd-core/src/main/java/net/sourceforge/pmd/lang/metrics/MetricOption.java

@@ -5,7 +5,12 @@
 package net.sourceforge.pmd.lang.metrics;
 
 /**
- * Option to pass to a metric. This is use to combine several behaviours together.
+ * Option to pass to a metric. Options modify the behaviour of a metric. You must bundle them into a
+ * {@link MetricOptions} to pass them all to a metric.
+ *
+ * <p>Combining options together may be done with a decorator pattern. If you use an AST visitor to compute your
+ * metric, look at the Cyclo metric in the Java framework for an example (the decorator pattern is not applicable as
+ * is on a visitor, a modified version of it has been implemented for the Java framework).
  *
  * @author Clément Fournier
  */

pmd-core/src/main/java/net/sourceforge/pmd/lang/metrics/MetricOptions.java

@@ -83,9 +83,9 @@ public class MetricOptions {
 
     @Override
     public String toString() {
-        return "MetricOptions{" +
-            "options=" + options +
-            '}';
+        return "MetricOptions{"
+            + "options=" + options
+            + '}';
     }
 
 
@@ -99,9 +99,6 @@ public class MetricOptions {
     }
 
 
-
-
-
     /**
      * Gets an options bundle from a list of options.
      *
@@ -124,18 +121,4 @@ public class MetricOptions {
         return POOL.get(version);
     }
 
-
-    /**
-     * Gets an array of options from a version.
-     *
-     * @param version The version to decompose
-     *
-     * @return An array of options
-     */
-    public static MetricOption[] toOptions(MetricOptions version) {
-        Set<MetricOption> options = version.getOptions();
-        return options.toArray(new MetricOption[options.size()]);
-    }
-
-
 }

pmd-core/src/main/java/net/sourceforge/pmd/lang/metrics/ParameterizedMetricKey.java

@@ -10,7 +10,7 @@ import java.util.Map;
 import net.sourceforge.pmd.lang.ast.Node;
 
 /**
- * Represents a key parameterized with its version. Used to index memoization maps.
+ * Represents a key parameterized with its options. Used to index memoization maps.
  *
  * @param <N> Type of node on which the memoized metric can be computed
  *
@@ -22,20 +22,20 @@ public final class ParameterizedMetricKey<N extends Node> {
 
     /** The metric key. */
     public final MetricKey<N> key;
-    /** The version of the metric. */
-    public final MetricOptions version;
+    /** The options of the metric. */
+    public final MetricOptions options;
 
 
     /** Used internally by the pooler. */
-    private ParameterizedMetricKey(MetricKey<N> key, MetricOptions version) {
+    private ParameterizedMetricKey(MetricKey<N> key, MetricOptions options) {
         this.key = key;
-        this.version = version;
+        this.options = options;
     }
 
 
     @Override
     public String toString() {
-        return "ParameterizedMetricKey{key=" + key.name() + ", version=" + version + '}';
+        return "ParameterizedMetricKey{key=" + key.name() + ", version=" + options + '}';
     }
 
 
@@ -43,13 +43,13 @@ public final class ParameterizedMetricKey<N extends Node> {
     public boolean equals(Object o) {
         return o instanceof ParameterizedMetricKey
             && ((ParameterizedMetricKey) o).key.equals(key)
-            && ((ParameterizedMetricKey) o).version.equals(version);
+            && ((ParameterizedMetricKey) o).options.equals(options);
     }
 
 
     @Override
     public int hashCode() {
-        return 31 * key.hashCode() + version.hashCode();
+        return 31 * key.hashCode() + options.hashCode();
     }
 
 
@@ -57,13 +57,13 @@ public final class ParameterizedMetricKey<N extends Node> {
      * Builds a parameterized metric key.
      *
      * @param key     The key
-     * @param version The version
-     * @param <N>     The type of node of the metrickey
+     * @param options The options
+     * @param <N>     The type of node of the metric key
      *
      * @return An instance of parameterized metric key corresponding to the parameters
      */
-    public static <N extends Node> ParameterizedMetricKey<N> getInstance(MetricKey<N> key, MetricOptions version) {
-        ParameterizedMetricKey<N> tmp = new ParameterizedMetricKey<>(key, version);
+    public static <N extends Node> ParameterizedMetricKey<N> getInstance(MetricKey<N> key, MetricOptions options) {
+        ParameterizedMetricKey<N> tmp = new ParameterizedMetricKey<>(key, options);
         if (!POOL.containsKey(tmp)) {
             POOL.put(tmp, tmp);
         }

pmd-java/src/test/java/net/sourceforge/pmd/lang/java/metrics/ParameterizedMetricKeyTest.java

@@ -73,7 +73,7 @@ public class ParameterizedMetricKeyTest {
         for (JavaClassMetricKey key : JavaClassMetricKey.values()) {
             ParameterizedMetricKey key1 = ParameterizedMetricKey.getInstance(key, DUMMY_VERSION_1);
             assertTrue(key1.toString().contains(key1.key.name()));
-            assertTrue(key1.toString().contains(key1.version.toString()));
+            assertTrue(key1.toString().contains(key1.options.toString()));
         }
     }
 
@@ -92,7 +92,7 @@ public class ParameterizedMetricKeyTest {
         assertTrue(key1 == key2);
         assertEquals(key1, key2);
         assertTrue(key1.toString().contains(key1.key.name()));
-        assertTrue(key1.toString().contains(key1.version.toString()));
+        assertTrue(key1.toString().contains(key1.options.toString()));
 
     }
 

pmd-java/src/test/java/net/sourceforge/pmd/lang/java/metrics/impl/AbstractMetricTestRule.java

@@ -107,7 +107,7 @@ public abstract class AbstractMetricTestRule extends AbstractJavaMetricsRule {
 
 
     /**
-     * Mappings of labels to versions for use in the version property.
+     * Mappings of labels to versions for use in the options property.
      *
      * @return A map of labels to versions
      */