OPENNLP-829 - added javadoc to DocumentCategorizer and DoccatModel
git-svn-id: https://svn.apache.org/repos/asf/opennlp/trunk@1725068 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/opennlp-tools/src/main/java/opennlp/tools/doccat/DoccatModel.java b/opennlp-tools/src/main/java/opennlp/tools/doccat/DoccatModel.java
index 08edfd5..e8c59fd 100644
--- a/opennlp-tools/src/main/java/opennlp/tools/doccat/DoccatModel.java
+++ b/opennlp-tools/src/main/java/opennlp/tools/doccat/DoccatModel.java
@@ -29,6 +29,9 @@
import opennlp.tools.util.InvalidFormatException;
import opennlp.tools.util.model.BaseModel;
+/**
+ * A model for document categorization
+ */
public class DoccatModel extends BaseModel {
private static final String COMPONENT_NAME = "DocumentCategorizerME";
diff --git a/opennlp-tools/src/main/java/opennlp/tools/doccat/DocumentCategorizer.java b/opennlp-tools/src/main/java/opennlp/tools/doccat/DocumentCategorizer.java
index 27cb73b..edd7b13 100644
--- a/opennlp-tools/src/main/java/opennlp/tools/doccat/DocumentCategorizer.java
+++ b/opennlp-tools/src/main/java/opennlp/tools/doccat/DocumentCategorizer.java
@@ -14,8 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
-
package opennlp.tools.doccat;
import java.util.Map;
@@ -28,31 +26,94 @@
public interface DocumentCategorizer {
/**
- * Categorizes the given text.
+ * Categorizes the given text, provided in separate tokens.
*
- * @param text
+ * @param text the tokens of text to categorize
+ * @return per category probabilities
*/
- public double[] categorize(String text[]);
+ double[] categorize(String text[]);
- public double[] categorize(String text[], Map<String, Object> extraInformation);
+ /**
+ * Categorizes the given text, provided in separate tokens.
+ *
+ * @param text the tokens of text to categorize
+ * @param extraInformation optional extra information to pass for evaluation
+ * @return per category probabilities
+ */
+ double[] categorize(String text[], Map<String, Object> extraInformation);
- public String getBestCategory(double[] outcome);
+ /**
+ * get the best category from previously generated outcome probabilities
+ *
+ * @param outcome a vector of outcome probabilities
+ * @return the best category String
+ */
+ String getBestCategory(double[] outcome);
- public int getIndex(String category);
+ /**
+ * get the index of a certain category
+ *
+ * @param category the category
+ * @return an index
+ */
+ int getIndex(String category);
- public String getCategory(int index);
+ /**
+ * get the category at a given index
+ *
+ * @param index the index
+ * @return a category
+ */
+ String getCategory(int index);
- public int getNumberOfCategories();
+ /**
+ * get the number of categories
+ *
+ * @return the no. of categories
+ */
+ int getNumberOfCategories();
- public double[] categorize(String documentText);
+ /**
+ * categorize a piece of text
+ *
+ * @param documentText the text to categorize
+ * @return the probabilities of each category (sum up to 1)
+ */
+ double[] categorize(String documentText);
- public double[] categorize(String documentText, Map<String, Object> extraInformation);
+ /**
+ * categorize a piece of text, providing extra metadata.
+ *
+ * @param documentText the text to categorize
+ * @param extraInformation extra metadata
+ * @return the probabilities of each category (sum up to 1)
+ */
+ double[] categorize(String documentText, Map<String, Object> extraInformation);
- public String getAllResults(double results[]);
+ /**
+ * get the name of the category associated with the given probabilties
+ *
+ * @param results the probabilities of each category
+ * @return the name of the outcome
+ */
+ String getAllResults(double results[]);
- public Map<String, Double> scoreMap(String text);
+ /**
+ * Returns a map in which the key is the category name and the value is the score
+ *
+ * @param text the input text to classify
+ * @return a map with the score as a key. The value is a Set of categories with the score.
+ */
+ Map<String, Double> scoreMap(String text);
- public SortedMap<Double, Set<String>> sortedScoreMap(String text);
+ /**
+ * Get a map of the scores sorted in ascending aorder together with their associated categories.
+ * Many categories can have the same score, hence the Set as value
+ *
+ * @param text the input text to classify
+ * @return a map with the score as a key. The value is a Set of categories with the score.
+ */
+ SortedMap<Double, Set<String>> sortedScoreMap(String text);
}
