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 {