Fix javadoc in the "commons" module

See #396.

Author: dr0i

metafacture-commons/src/main/java/org/metafacture/commons/ResourceUtil.java

@@ -148,6 +148,13 @@ public static Properties loadProperties(final String location)
         return loadProperties(getStream(location));
     }
 
+    /**
+     * Loads properties from an InputStream.
+     *
+     * @param stream properties as InputStream
+     * @return Properties
+     * @throws IOException
+     */
     public static Properties loadProperties(final InputStream stream)
             throws IOException {
         final Properties properties;
@@ -156,10 +163,24 @@ public static Properties loadProperties(final InputStream stream)
         return properties;
     }
 
+    /**
+     * Loads properties from an URL.
+     *
+     * @param url properties as URL
+     * @return Properties
+     * @throws IOException
+     */
     public static Properties loadProperties(final URL url) throws IOException {
         return loadProperties(url.openStream());
     }
 
+    /**
+     * Loads a text file.
+     *
+     * @param location filename
+     * @return the content of the file
+     * @throws IOException
+     */
     public static String loadTextFile(final String location) throws IOException {
         final StringBuilder builder = new StringBuilder();
         final BufferedReader reader = new BufferedReader(getReader(location));
@@ -173,6 +194,14 @@ public static String loadTextFile(final String location) throws IOException {
         return builder.toString();
     }
 
+    /**
+     * * Loads a text file.
+     *
+     * @param location the filename
+     * @param list a List of Strings
+     * @return a List of Strings of the content of the filename, line-by-line
+     * @throws IOException
+     */
     public static List<String> loadTextFile(final String location,
             final List<String> list) throws IOException {
         final BufferedReader reader = new BufferedReader(getReader(location));
@@ -186,13 +215,28 @@ public static List<String> loadTextFile(final String location,
         return list;
     }
 
+    /**
+     * Reads an InputStream with the given Charset.
+     *
+     * @param inputStream the InputStream
+     * @param encoding    the Charset
+     * @return a String of the content of the InputStream
+     * @throws IOException
+     */
     public static String readAll(final InputStream inputStream, final Charset encoding)
             throws IOException {
         try (Reader reader = new InputStreamReader(inputStream, encoding)) {
             return readAll(reader);
         }
     }
 
+    /**
+     * Reads a Reader.
+     *
+     * @param reader the Reader
+     * @return a String of the content of the Reader
+     * @throws IOException
+     */
     public static String readAll(final Reader reader) throws IOException {
         final StringBuilder loadedText = new StringBuilder();
         try (Reader bufferedReader = new BufferedReader(reader)) {

metafacture-commons/src/main/java/org/metafacture/commons/StringUtil.java

@@ -34,6 +34,14 @@ private StringUtil() {
         // no instances allowed
     }
 
+    /**
+     * Sets a fallback of an Object if the the Object is null.
+     *
+     * @param <O>           a class
+     * @param value         the Object
+     * @param fallbackValue the default Object
+     * @return an Object
+     */
     public static <O> O fallback(final O value, final O fallbackValue) {
         if (value == null) {
             return fallbackValue;
@@ -55,6 +63,17 @@ public static String format(final String format, final boolean ignoreMissingVars
         return format(format, DEFAULT_VARSTART, DEFAULT_VAREND, ignoreMissingVars, variables);
     }
 
+    /**
+     * Formats a String. If a String has a variable it will be replaced based on a
+     * Map. The start and the end of indicating this variable must be defined.
+     *
+     * @param format            the String to be formatted
+     * @param varStartIndicator a String indicating the start of a variable
+     * @param varEndIndicator   a String indicating the end of a variable
+     * @param ignoreMissingVars boolean if an unassigned variable should be ignored
+     * @param variables         a Map of variable names and their values
+     * @return a formatted String
+     */
     public static String format(final String format, final String varStartIndicator, final String varEndIndicator,
             final boolean ignoreMissingVars, final Map<String, String> variables) {
         if (format.indexOf(varStartIndicator) < 0) { // shortcut if there is

metafacture-commons/src/main/java/org/metafacture/commons/TimeUtil.java

@@ -39,6 +39,13 @@ private TimeUtil() {
         // No instances allowed
     }
 
+    /**
+     * Formats a duration to human readable abbrevations. See {@link TimeUtilTest}
+     * how to use it.
+     *
+     * @param duration a long value of the duration
+     * @return a human readable format of the duration
+     */
     public static String formatDuration(final long duration) {
         long major = duration;
         long minor = 0;

metafacture-commons/src/main/java/org/metafacture/commons/XmlUtil.java

@@ -49,6 +49,13 @@ public static String nodeToString(final Node node) {
         return nodeToString(node, false);
     }
 
+    /**
+     * Converts a Node to a String, with or without an XML declaration
+     *
+     * @param node        the Node
+     * @param omitXMLDecl boolean if an XML declaration is ommited or not
+     * @return a String representation of the Node
+     */
     public static String nodeToString(final Node node,
             final boolean omitXMLDecl) {
         final StringWriter writer = new StringWriter();
@@ -79,6 +86,12 @@ public static String nodeToString(final Node node,
         return writer.toString();
     }
 
+    /**
+     * Converts a NodeList to a String.
+     *
+     * @param nodes the NodeList
+     * @return a String representation od the NodeList
+     */
     public static String nodeListToString(final NodeList nodes) {
         final StringBuilder builder = new StringBuilder();
 
@@ -89,6 +102,12 @@ public static String nodeListToString(final NodeList nodes) {
         return builder.toString();
     }
 
+    /**
+     * Checks if a String is an Xml Mime Type.
+     *
+     * @param mimeType the Mime Type
+     * @return boolean if a String is an Xml Mime Type
+     */
     public static boolean isXmlMimeType(final String mimeType) {
         if (mimeType == null) {
             return false;
@@ -102,6 +121,14 @@ public static String escape(final String unescaped) {
         return escape(unescaped, true);
     }
 
+    /**
+     * Escapes XML special characters. May also escape non-ASCII characters (aka
+     * unicode).
+     *
+     * @param unescaped     the String to be unescaped
+     * @param escapeUnicode boolean if unicode should be also escaped
+     * @return the escaped String
+     */
     public static String escape(final String unescaped, final boolean escapeUnicode) {
         return unescaped.codePoints()
                 .mapToObj(value -> escapeCodePoint(value, escapeUnicode))

metafacture-commons/src/main/java/org/metafacture/commons/reflection/ConfigurableClass.java

@@ -54,6 +54,11 @@ public Class<T> getPlainClass() {
         return plainClass;
     }
 
+    /**
+     * Gets all "public set" methods of this class.
+     *
+     * @return the Map of all setter methods of this class
+     */
     public Map<String, Method> getSetters() {
         if (settersCache == null) {
             initSettersCache();
@@ -82,6 +87,11 @@ private boolean isSetter(final Method method) {
         return false;
     }
 
+    /**
+     * Gets the class types of the setter methods.
+     *
+     * @return a Map of the setter methods name and their types
+     */
     public Map<String, Class<?>> getSetterTypes() {
         final Map<String, Class<?>> setterTypes = new HashMap<>();
         for (final Map.Entry<String, Method> method : getSetters().entrySet()) {
@@ -95,6 +105,14 @@ public T newInstance() {
         return newInstance(Collections.emptyMap());
     }
 
+    /**
+     * Creates an instance of the class using the first constructor that matches the
+     * varargs argument of the methods.
+     *
+     * @param setterValues
+     * @param constructorArgs
+     * @return the new instance
+     */
     public T newInstance(final Map<String, String> setterValues, final Object... constructorArgs) {
         try {
             final Constructor<T> constructor = findConstructor(constructorArgs);

metafacture-commons/src/main/java/org/metafacture/commons/reflection/ObjectFactory.java

@@ -40,6 +40,12 @@ public class ObjectFactory<T> {
     public ObjectFactory() {
     }
 
+    /**
+     * Loads classes from a map.
+     *
+     * @param classMap the map of classes
+     * @param baseType the object type of the classes
+     */
     public final void loadClassesFromMap(final Map<?, ?> classMap, final Class<T> baseType) {
         final ClassLoader loader = ReflectionUtil.getContextClassLoader();
         for (final Entry<?, ?> entry : classMap.entrySet()) {
@@ -61,6 +67,14 @@ public final T newInstance(final String key, final Object... constructorArgs) {
         return newInstance(key, Collections.emptyMap(), constructorArgs);
     }
 
+    /**
+     * Returns a new instance of a ConfigurableClass.
+     *
+     * @param key             the name of the class
+     * @param values          the Map of Strings of the setters
+     * @param constructorArgs the args of the constructor
+     * @return a new instance
+     */
     public final T newInstance(final String key, final Map<String, String> values, final Object... constructorArgs) {
         if (!classes.containsKey(key)) {
             throw new NoSuchElementException("no registered class for: " + key);

metafacture-commons/src/main/java/org/metafacture/commons/reflection/ReflectionUtil.java

@@ -28,6 +28,10 @@ private ReflectionUtil() {
         throw new AssertionError("No instances allowed");
     }
 
+    /**
+     * @return the context ClassLoader for this thread, or null indicating the
+     *         system class loader (or, failing that, the bootstrap class loader)
+     */
     public static ClassLoader getContextClassLoader() {
         final ClassLoader loader = Thread.currentThread().getContextClassLoader();
         if (loader == null) {
@@ -40,6 +44,15 @@ public static <T> ConfigurableClass<? extends T> loadClass(final String classNam
         return loadClass(getContextClassLoader(), className, baseType);
     }
 
+    /**
+     * Wraps a Class to a ConfigurableClass.
+     *
+     * @param <T>       the object type of the ConfigurableClass
+     * @param loader    the ClassLoader
+     * @param className the name of the class
+     * @param baseType  the object typed class to be wrapped
+     * @return the ConfigurableClass
+     */
     public static <T> ConfigurableClass<? extends T> loadClass(final ClassLoader loader, final String className, final Class<T> baseType) {
         final Class<?> clazz;
         try {

metafacture-commons/src/main/java/org/metafacture/commons/tries/SetMatcher.java

@@ -36,6 +36,12 @@ public final class SetMatcher<T> {
     public SetMatcher() {
     }
 
+    /**
+     * Puts a value to a key.
+     *
+     * @param key   the key
+     * @param value the value
+     */
     public void put(final String key, final T value) {
         if (isPrepared) {
             throw new IllegalStateException("keys cannot be added during matching.");
@@ -63,6 +69,12 @@ else if (next.getValue() == null) {
         }
     }
 
+    /**
+     * Gets the List of Matches of a text.
+     *
+     * @param text the text
+     * @return List of Matches
+     */
     public List<Match<T>> match(final String text) {
         if (!isPrepared) {
             prepare();
@@ -173,6 +185,13 @@ public static final class Match<T> {
         private final int start;
         private final int length;
 
+        /**
+         * Constructs a Match.
+         *
+         * @param value the value
+         * @param start the position
+         * @param length the length
+         */
         public Match(final T value, final int start, final int length) {
             this.value = value;
             this.start = start;

metafacture-commons/src/main/java/org/metafacture/commons/tries/SetReplacer.java

@@ -25,6 +25,8 @@
 import java.util.Map;
 
 /**
+ * Replaces Strings by other Strings.
+ *
  * @author Markus Michael Geipel
  *
  */
@@ -34,20 +36,37 @@ public final class SetReplacer {
     public SetReplacer() {
     }
 
-    public void addReplacement(final String key, final String with) {
-        matcher.put(key, with);
+    /**
+     * Adds a replacement of a String by an other String.
+     *
+     * @param toReplace   String to replace
+     * @param replacement String of replacement
+     */
+    public void addReplacement(final String toReplace, final String replacement) {
+        matcher.put(toReplace, replacement);
     }
 
+    /**
+     * Adds replacements given as a Map of Strings.
+     *
+     * @param replacements the Map of Strings to be replaced
+     */
     public void addReplacements(final Map<String, String> replacements) {
         for (final Entry<String, String> entry : replacements.entrySet()) {
             addReplacement(entry.getKey(), entry.getValue());
         }
     }
 
+    /**
+     * Replaces the Strings defined with {@link #addReplacement(String, String)} in
+     * the text.
+     *
+     * @param text
+     * @return the text with the replacements
+     */
     public String replaceIn(final String text) {
         final List<SetMatcher.Match<String>> matches = matcher.match(text);
         final StringBuilder builder = new StringBuilder();
-
         int lastCut = 0;
 
         Collections.sort(matches, new Comparator<SetMatcher.Match<String>>() {
@@ -56,25 +75,17 @@ public int compare(final Match<String> o1, final Match<String> o2) {
                 final int delta = o1.getStart() - o2.getStart();
                 return delta < 0 ? -1 : delta > 0 ? 1 : o1.getLength() > o2.getLength() ? -1 : 1;
             }
-
         });
 
         for (final SetMatcher.Match<String> match : matches) {
-
             if (match.getStart() < lastCut) {
                 continue;
             }
-
-            // System.out.println(match.getStart() + " "+ match.getValue() +" "+
-            // match.getLength());
-
             builder.append(text.substring(lastCut, match.getStart()));
             builder.append(match.getValue());
-
             lastCut = match.getStart() + match.getLength();
         }
         builder.append(text.substring(lastCut, text.length()));
-
         return builder.toString();
     }