Javadoc fixes and improvements. (#396)

Author: blackwinter

metafacture-biblio/src/main/java/org/metafacture/biblio/iso2709/Label.java

@@ -17,7 +17,7 @@
 package org.metafacture.biblio.iso2709;
 
 /**
- * Provides read access to the record label of a ISO 2709:2008 formatted
+ * Provides read access to the record label of an ISO 2709:2008 formatted
  * record. The record label consists of the first 24 octets of the record.
  * <p>
  * Use {@link LabelBuilder} if write access to the label is required.

metafacture-biblio/src/main/java/org/metafacture/biblio/iso2709/RecordBuilder.java

@@ -311,7 +311,7 @@ public void endDataField() {
     /**
      * Appends a subfield.
      *
-     * @param value String of the to be appended subfield
+     * @param value String of the subfield to be appended
      */
     public void appendSubfield(final String value) {
         requireInDataField();
@@ -323,7 +323,7 @@ public void appendSubfield(final String value) {
      * Appends a subfield in dependency of an identifier.
      *
      * @param identifier char array of an identifier
-     * @param value      String of the to be appended subfield
+     * @param value      String of the subfield to be appended
      */
     public void appendSubfield(final char[] identifier, final String value) {
         requireInDataField();

metafacture-biblio/src/main/java/org/metafacture/biblio/iso2709/RecordFormat.java

@@ -56,9 +56,9 @@ public final class RecordFormat {
      *
      * @param indicatorLength       the length of the indicator
      * @param identifierLength      the length of the identifier
-     * @param fieldLengthLength     the length of the field
-     * @param fieldStartLength      the length of the indicator
-     * @param implDefinedPartLength the length of the part
+     * @param fieldLengthLength     the length of the field length
+     * @param fieldStartLength      the length of the field start
+     * @param implDefinedPartLength the length of the defined part
      */
     public RecordFormat(final int indicatorLength, final int identifierLength,
             final int fieldLengthLength, final int fieldStartLength,
@@ -201,9 +201,9 @@ public Builder withIdentifierLength(final int currentIdentifierLength) {
         }
 
         /**
-         * Returns a new Builder with defined field length.
+         * Returns a new Builder with defined field length length.
          *
-         * @param currentFieldLengthLength the length of the field
+         * @param currentFieldLengthLength the length of the field length
          * @return Builder
          */
         public Builder withFieldLengthLength(final int currentFieldLengthLength) {
@@ -229,7 +229,7 @@ public Builder withFieldStartLength(final int currentFieldStartLength) {
         /**
          * Returns a new Builder with defined part length.
          *
-         * @param currentImplDefinedPartLength the length of the part
+         * @param currentImplDefinedPartLength the length of the defined part
          * @return Builder
          */
         public Builder withImplDefinedPartLength(final int currentImplDefinedPartLength) {

metafacture-biblio/src/main/java/org/metafacture/biblio/marc21/Marc21Encoder.java

@@ -82,7 +82,6 @@ public final class Marc21Encoder extends
 
     /**
      * Initializes the encoder with MARC 21 constants and charset.
-     *
      */
     public Marc21Encoder() {
         builder = new RecordBuilder(Marc21Constants.MARC21_FORMAT);

metafacture-biblio/src/main/java/org/metafacture/biblio/marc21/MarcXmlEncoder.java

@@ -236,17 +236,19 @@ private void writeFooter() {
         writeRaw(ROOT_CLOSE);
     }
 
-    /** Writes a unescaped sequence
-    *   @param str
-    *             the unescaped sequence to be written
+    /**
+    * Writes an unescaped sequence.
+    *
+    * @param str the unescaped sequence to be written
     */
     private void writeRaw(final String str) {
         builder.append(str);
     }
 
-    /** Writes a escaped sequence
-    *   @param str
-    *             the unescaped sequence to be written
+    /**
+    * Writes an escaped sequence.
+    *
+    * @param str the unescaped sequence to be written
     */
     private void writeEscaped(final String str) {
         builder.append(XmlUtil.escape(str, false));

metafacture-biblio/src/main/java/org/metafacture/biblio/pica/PicaDecoder.java

@@ -219,7 +219,7 @@ public boolean getIgnoreMissingIdn() {
     }
 
     /**
-     * Controls whether decomposed unicode characters in field values are
+     * Controls whether decomposed Unicode characters in field values are
      * normalised to their precomposed version. By default no normalisation is
      * applied. The normalisation is only applied to values not to field or
      * subfield names.
@@ -229,7 +229,7 @@ public boolean getIgnoreMissingIdn() {
      * <p>
      * <strong>Default value: {@code false}</strong>
      *
-     * @param normalizeUTF8 if true, decomposed unicode characters in values are
+     * @param normalizeUTF8 if true, decomposed Unicode characters in values are
      *                      normalised to their precomposed version.
      */
     public void setNormalizeUTF8(final boolean normalizeUTF8) {

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

@@ -164,7 +164,7 @@ public static Properties loadProperties(final InputStream stream)
     }
 
     /**
-     * Loads properties from an URL.
+     * Loads properties from a URL.
      *
      * @param url properties as URL
      * @return Properties
@@ -177,7 +177,7 @@ public static Properties loadProperties(final URL url) throws IOException {
     /**
      * Loads a text file.
      *
-     * @param location filename
+     * @param location the filename
      * @return the content of the file
      * @throws IOException
      */
@@ -198,8 +198,8 @@ public static String loadTextFile(final String location) throws IOException {
      * * 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
+     * @param list a List of Strings to append the lines of the file to
+     * @return the List of Strings with the lines of the file appended
      * @throws IOException
      */
     public static List<String> loadTextFile(final String location,

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

@@ -35,12 +35,12 @@ private StringUtil() {
     }
 
     /**
-     * Sets a fallback of an Object if the the Object is null.
+     * Returns a fallback of an object if the object is null.
      *
-     * @param <O>           a class
-     * @param value         the Object
-     * @param fallbackValue the default Object
-     * @return an Object
+     * @param <O>           the type of the object
+     * @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) {

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

@@ -53,7 +53,7 @@ public static String nodeToString(final Node node) {
      * 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
+     * @param omitXMLDecl boolean if an XML declaration is omitted or not
      * @return a String representation of the Node
      */
     public static String nodeToString(final Node node,
@@ -90,7 +90,7 @@ public static String nodeToString(final Node node,
      * Converts a NodeList to a String.
      *
      * @param nodes the NodeList
-     * @return a String representation od the NodeList
+     * @return a String representation of the NodeList
      */
     public static String nodeListToString(final NodeList nodes) {
         final StringBuilder builder = new StringBuilder();
@@ -103,10 +103,10 @@ public static String nodeListToString(final NodeList nodes) {
     }
 
     /**
-     * Checks if a String is an Xml Mime Type.
+     * Checks if a String is an XML MIME type.
      *
-     * @param mimeType the Mime Type
-     * @return boolean 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) {
@@ -123,10 +123,10 @@ public static String escape(final String unescaped) {
 
     /**
      * Escapes XML special characters. May also escape non-ASCII characters (aka
-     * unicode).
+     * Unicode).
      *
      * @param unescaped     the String to be unescaped
-     * @param escapeUnicode boolean if unicode should be also escaped
+     * @param escapeUnicode boolean if Unicode should be also escaped
      * @return the escaped String
      */
     public static String escape(final String unescaped, final boolean escapeUnicode) {

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

@@ -55,9 +55,9 @@ public Class<T> getPlainClass() {
     }
 
     /**
-     * Gets all "public set" methods of this class.
+     * Gets all public "set" methods of this class.
      *
-     * @return the Map of all setter methods of this class
+     * @return the Map of the setter methods of this class
      */
     public Map<String, Method> getSetters() {
         if (settersCache == null) {
@@ -88,9 +88,9 @@ private boolean isSetter(final Method method) {
     }
 
     /**
-     * Gets the class types of the setter methods.
+     * Gets the parameter types of the setter methods.
      *
-     * @return a Map of the setter methods name and their types
+     * @return a Map of the setter method names and their types
      */
     public Map<String, Class<?>> getSetterTypes() {
         final Map<String, Class<?>> setterTypes = new HashMap<>();