OPENNLP-1694: Enhance JavaDoc in util.featuregen package (#739)

Author: mawiesne

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/AdditionalContextFeatureGenerator.java

@@ -34,7 +34,6 @@ public class AdditionalContextFeatureGenerator implements AdaptiveFeatureGenerat
   public void createFeatures(List<String> features, String[] tokens, int index, String[] preds) {
 
     if (additionalContext != null && additionalContext.length != 0) {
-
       String[] context = additionalContext[index];
 
       for (String s : context) {

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/AggregatedFeatureGenerator.java

@@ -25,16 +25,17 @@
 
 /**
  * The {@link AggregatedFeatureGenerator} aggregates a set of
- * {@link AdaptiveFeatureGenerator}s and calls them to generate the features.
+ * {@link AdaptiveFeatureGenerator feature generators} and calls them
+ * to generate the features.
  */
 public class AggregatedFeatureGenerator implements AdaptiveFeatureGenerator {
 
   private Collection<AdaptiveFeatureGenerator> generators;
 
   /**
-   * Initializes the current instance.
+   * Initializes an {@link AggregatedFeatureGenerator} via specified {@code generators}.
    *
-   * @param generators array of generators, null values are not permitted
+   * @param generators A collection of generators, {@code null} values are not permitted.
    */
   public AggregatedFeatureGenerator(AdaptiveFeatureGenerator... generators) {
 
@@ -49,25 +50,29 @@ public AggregatedFeatureGenerator(AdaptiveFeatureGenerator... generators) {
     this.generators = Collections.unmodifiableCollection(this.generators);
   }
 
+  /**
+   * Initializes an {@link AggregatedFeatureGenerator} via specified {@code generators}.
+   *
+   * @param generators A collection of generators, {@code null} values are not permitted.
+   */
   public AggregatedFeatureGenerator(Collection<AdaptiveFeatureGenerator> generators) {
     this(generators.toArray(new AdaptiveFeatureGenerator[0]));
   }
 
   /**
    * Calls the {@link AdaptiveFeatureGenerator#clearAdaptiveData()} method
-   * on all aggregated {@link AdaptiveFeatureGenerator}s.
+   * on all aggregated {@link AdaptiveFeatureGenerator feature generators}.
    */
   @Override
   public void clearAdaptiveData() {
-
     for (AdaptiveFeatureGenerator generator : generators) {
       generator.clearAdaptiveData();
     }
   }
 
   /**
    * Calls the {@link AdaptiveFeatureGenerator#createFeatures(List, String[], int, String[])}
-   * method on all aggregated {@link AdaptiveFeatureGenerator}s.
+   * method on all aggregated {@link AdaptiveFeatureGenerator feature generators}.
    */
   @Override
   public void createFeatures(List<String> features, String[] tokens, int index,
@@ -80,20 +85,19 @@ public void createFeatures(List<String> features, String[] tokens, int index,
 
   /**
    * Calls the {@link AdaptiveFeatureGenerator#updateAdaptiveData(String[], String[])}
-   * method on all aggregated {@link AdaptiveFeatureGenerator}s.
+   * method on all aggregated {@link AdaptiveFeatureGenerator feature generators}.
    */
   public void updateAdaptiveData(String[] tokens, String[] outcomes) {
-
     for (AdaptiveFeatureGenerator generator : generators) {
       generator.updateAdaptiveData(tokens, outcomes);
     }
   }
 
   /**
    * Retrieves a {@link Collections} of all aggregated
-   * {@link AdaptiveFeatureGenerator}s.
+   * {@link AdaptiveFeatureGenerator feature generators}.
    *
-   * @return all aggregated generators
+   * @return All aggregated generators in use.
    */
   public Collection<AdaptiveFeatureGenerator> getGenerators() {
     return generators;

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/AggregatedFeatureGeneratorFactory.java

@@ -24,6 +24,9 @@
 import opennlp.tools.util.InvalidFormatException;
 
 /**
+ * A {@link GeneratorFactory} that produces {@link AggregatedFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
  * @see AggregatedFeatureGenerator
  */
 public class AggregatedFeatureGeneratorFactory

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BigramNameFeatureGenerator.java

@@ -19,6 +19,11 @@
 
 import java.util.List;
 
+/**
+ * Adds bigram features based on tokens and token classes.
+ *
+ * @see AdaptiveFeatureGenerator
+ */
 public class BigramNameFeatureGenerator implements AdaptiveFeatureGenerator {
 
   @Override

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BigramNameFeatureGeneratorFactory.java

@@ -19,6 +19,12 @@
 
 import opennlp.tools.util.InvalidFormatException;
 
+/**
+ * A {@link GeneratorFactory} that produces {@link BigramNameFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
+ * @see BigramNameFeatureGenerator
+ */
 public class BigramNameFeatureGeneratorFactory
     extends GeneratorFactory.AbstractXmlFeatureGeneratorFactory {
 

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownBigramFeatureGenerator.java

@@ -21,6 +21,9 @@
 
 /**
  * Generates Brown cluster features for token bigrams.
+ *
+ * @see AdaptiveFeatureGenerator
+ * @see BrownCluster
  */
 public class BrownBigramFeatureGenerator implements AdaptiveFeatureGenerator {
 
@@ -31,8 +34,10 @@ public class BrownBigramFeatureGenerator implements AdaptiveFeatureGenerator {
   private final BrownCluster brownCluster;
 
   /**
-   * Creates a new Brown Cluster bigram feature generator.
-   * @param brownCluster A {@link BrownCluster}.
+   * Initializes a {@link BrownBigramFeatureGenerator} generator via a specified
+   * {@link BrownCluster}.
+   * 
+   * @param brownCluster The token {@link BrownCluster dictionary} to use.
    */
   public BrownBigramFeatureGenerator(BrownCluster brownCluster) {
     this.brownCluster = brownCluster;

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownCluster.java

@@ -34,8 +34,7 @@
 import opennlp.tools.util.model.SerializableArtifact;
 
 /**
- *
- * Class to load a Brown cluster document: word\tword_class\tprob
+ * Class to load a Brown cluster document in the format: {@code word\tword_class\tprob}.
  * <p>
  * Originally available at: <a href="http://metaoptimize.com/projects/wordreprs/">
  * http://metaoptimize.com/projects/wordreprs/</a>.
@@ -69,8 +68,8 @@ public void serialize(BrownCluster artifact, OutputStream out)
   /**
    * Instatiates a {@link BrownCluster} and its related token to cluster map
    * via an {@link InputStream}.
-   * <p>
-   * <b>Note:</b>
+   * 
+   * @implNote
    * Only tokens with frequency bigger than {@code 5} will be added.
    * 
    * @param in A valid, open {@link InputStream} to read from.
@@ -101,7 +100,7 @@ else if (lineArray.length == 2) {
    * Check if a token is in the Brown:paths, token map.
    * 
    * @param string the token to look-up
-   * @return the brown class if such token is in the brown cluster map
+   * @return the brown class if such token is in the brown cluster map.
    */
   public String lookupToken(String string) {
     return tokenToClusterMap.get(string);

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownClusterBigramFeatureGeneratorFactory.java

@@ -24,7 +24,10 @@
 import opennlp.tools.util.model.ArtifactSerializer;
 
 /**
- * Generates Brown clustering features for token bigrams.
+ * A {@link GeneratorFactory} that produces {@link BrownBigramFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
+ * @see BrownBigramFeatureGenerator
  */
 public class BrownClusterBigramFeatureGeneratorFactory
     extends GeneratorFactory.AbstractXmlFeatureGeneratorFactory {

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownClusterTokenClassFeatureGeneratorFactory.java

@@ -24,7 +24,10 @@
 import opennlp.tools.util.model.ArtifactSerializer;
 
 /**
- * Generates Brown clustering features for token classes.
+ * A {@link GeneratorFactory} that produces {@link BrownTokenClassFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
+ * @see BrownTokenClassFeatureGenerator
  */
 public class BrownClusterTokenClassFeatureGeneratorFactory
     extends GeneratorFactory.AbstractXmlFeatureGeneratorFactory {

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownClusterTokenFeatureGeneratorFactory.java

@@ -24,7 +24,10 @@
 import opennlp.tools.util.model.ArtifactSerializer;
 
 /**
- * Generates Brown clustering features for current token.
+ * A {@link GeneratorFactory} that produces {@link BrownTokenFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
+ * @see BrownTokenFeatureGenerator
  */
 public class BrownClusterTokenFeatureGeneratorFactory
     extends GeneratorFactory.AbstractXmlFeatureGeneratorFactory {

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownTokenClassFeatureGenerator.java

@@ -21,9 +21,14 @@
 
 /**
  * Generates {@link BrownCluster} features for current token and token class.
+ *
+ * @see AdaptiveFeatureGenerator
+ * @see BrownCluster
  */
 public class BrownTokenClassFeatureGenerator implements AdaptiveFeatureGenerator {
 
+  private static final String PREFIX = "c,browncluster=";
+
   private final BrownCluster brownLexicon;
 
   /**
@@ -44,7 +49,7 @@ public void createFeatures(List<String> features, String[] tokens, int index,
     List<String> wordClasses = BrownTokenClasses.getWordClasses(tokens[index], brownLexicon);
 
     for (String wordClass : wordClasses) {
-      features.add("c," + "browncluster" + "=" + wordShape + "," + wordClass);
+      features.add(PREFIX + wordShape + "," + wordClass);
     }
   }
 

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownTokenClasses.java

@@ -35,9 +35,9 @@ public class BrownTokenClasses {
    * It provides a list containing the pathLengths for a token if found
    * in the Map:token,BrownClass.
    *
-   * @param token the token to be looked up in the brown clustering map
-   * @param brownLexicon the Brown clustering map
-   * @return the list of the paths for a token
+   * @param token The token to be looked up in the brown clustering map
+   * @param brownLexicon The {@link BrownCluster} clustering map
+   * @return A list of the paths for a token.
    */
   public static List<String> getWordClasses(String token, BrownCluster brownLexicon) {
     if (brownLexicon.lookupToken(token) == null) {

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/BrownTokenFeatureGenerator.java

@@ -21,11 +21,22 @@
 
 /**
  * Generates {@link BrownCluster} features for current token.
+ *
+ * @see AdaptiveFeatureGenerator
+ * @see BrownCluster
  */
 public class BrownTokenFeatureGenerator implements AdaptiveFeatureGenerator {
 
+  private static final String PREFIX = "browncluster=";
+
   private final BrownCluster brownLexicon;
 
+  /**
+   * Instantiates a {@link BrownTokenFeatureGenerator} via a specified
+   * {@link BrownCluster}.
+   *
+   * @param dict The token {@link BrownCluster dictionary} to use.
+   */
   public BrownTokenFeatureGenerator(BrownCluster dict) {
     this.brownLexicon = dict;
   }
@@ -37,7 +48,7 @@ public void createFeatures(List<String> features, String[] tokens, int index,
     List<String> wordClasses = BrownTokenClasses.getWordClasses(tokens[index], brownLexicon);
 
     for (String wordClass : wordClasses) {
-      features.add("browncluster" + "=" + wordClass);
+      features.add(PREFIX + wordClass);
     }
   }
 

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/CachedFeatureGenerator.java

@@ -25,6 +25,8 @@
 
 /**
  * Caches features of the aggregated {@link AdaptiveFeatureGenerator generators}.
+ *
+ * @see Cache
  */
 public class CachedFeatureGenerator implements AdaptiveFeatureGenerator {
 

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/CachedFeatureGeneratorFactory.java

@@ -21,6 +21,9 @@
 import opennlp.tools.util.InvalidFormatException;
 
 /**
+ * A {@link GeneratorFactory} that produces {@link CachedFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
  * @see CachedFeatureGenerator
  */
 public class CachedFeatureGeneratorFactory

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/CharacterNgramFeatureGenerator.java

@@ -26,6 +26,8 @@
 /**
  * The {@link CharacterNgramFeatureGenerator} uses character ngrams to
  * generate features about each token.
+ *
+ * @see AdaptiveFeatureGenerator
  */
 public class CharacterNgramFeatureGenerator implements AdaptiveFeatureGenerator {
 
@@ -35,7 +37,7 @@ public class CharacterNgramFeatureGenerator implements AdaptiveFeatureGenerator
   private final int maxLength;
 
   /**
-   * Initializes a {@link CharacterNgramFeatureGenerator}.
+   * Initializes a {@link CharacterNgramFeatureGenerator} with the specified parameters.
    *
    * @param minLength The minimum length to use. Must not be negative.
    * @param maxLength The maximum length to use. Must not be negative.
@@ -46,8 +48,8 @@ public CharacterNgramFeatureGenerator(int minLength, int maxLength) {
   }
 
   /**
-   * Initializes a {@link CharacterNgramFeatureGenerator} with
-   * min length of {@code 2} and max length of {@code 5} for ngrams.
+   * Initializes a {@link CharacterNgramFeatureGenerator} with default values for ngrams.
+   * The minimal length is set to {@code 2} and maximum length to a value of {@code 5}.
    */
   public CharacterNgramFeatureGenerator() {
     this(2, 5);

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/CharacterNgramFeatureGeneratorFactory.java

@@ -20,6 +20,9 @@
 import opennlp.tools.util.InvalidFormatException;
 
 /**
+ * A {@link GeneratorFactory} that produces {@link CharacterNgramFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
  * @see CharacterNgramFeatureGenerator
  */
 public class CharacterNgramFeatureGeneratorFactory

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/DefinitionFeatureGeneratorFactory.java

@@ -20,13 +20,14 @@
 import opennlp.tools.util.InvalidFormatException;
 
 /**
- * @see DefinitionFeatureGeneratorFactory
+ * A {@link GeneratorFactory} that produces {@link OutcomePriorFeatureGenerator} instances
+ * when {@link #create()} is called.
+ *
+ * @see OutcomePriorFeatureGenerator
  */
 public class DefinitionFeatureGeneratorFactory
     extends GeneratorFactory.AbstractXmlFeatureGeneratorFactory {
 
-  private static final String ELEMENT_NAME = "definition";
-
   public DefinitionFeatureGeneratorFactory() {
     super();
   }

opennlp-tools/src/main/java/opennlp/tools/util/featuregen/DictionaryFeatureGenerator.java

@@ -24,8 +24,8 @@
 import opennlp.tools.namefind.DictionaryNameFinder;
 
 /**
- * The {@link DictionaryFeatureGenerator} uses the {@link DictionaryNameFinder}
- * to generated features for detected names based on the {@link InSpanGenerator}.
+ * The {@link DictionaryFeatureGenerator} uses a {@link DictionaryNameFinder}
+ * to generate features for detected names based on the {@link InSpanGenerator}.
  *
  * @see Dictionary
  * @see DictionaryNameFinder
@@ -35,16 +35,27 @@ public class DictionaryFeatureGenerator implements AdaptiveFeatureGenerator {
 
   private InSpanGenerator isg;
 
+  /**
+   * Initializes a {@link DictionaryFeatureGenerator} with the specified {@link Dictionary}.
+   *
+   * @param dict The {@link Dictionary} to use. Must not be {@code null}.
+   */
   public DictionaryFeatureGenerator(Dictionary dict) {
-    this("",dict);
+    this("", dict);
   }
 
+  /**
+   * Initializes a {@link DictionaryFeatureGenerator} with the specified parameters.
+   *
+   * @param prefix The prefix to set. Must not be {@code null} but may be empty.
+   * @param dict The {@link Dictionary} to use. Must not be {@code null}.
+   */
   public DictionaryFeatureGenerator(String prefix, Dictionary dict) {
-    setDictionary(prefix,dict);
+    setDictionary(prefix, dict);
   }
 
   public void setDictionary(Dictionary dict) {
-    setDictionary("",dict);
+    setDictionary("", dict);
   }
 
   public void setDictionary(String name, Dictionary dict) {