Javadoc

Author: garydgregory

src/main/java/org/apache/commons/text/translate/AggregateTranslator.java

@@ -39,7 +39,7 @@ public class AggregateTranslator extends CharSequenceTranslator {
     /**
      * Specify the translators to be used at creation time.
      *
-     * @param translators CharSequenceTranslator array to aggregate
+     * @param translators CharSequenceTranslator array to aggregate.
      */
     public AggregateTranslator(final CharSequenceTranslator... translators) {
         if (translators != null) {

src/main/java/org/apache/commons/text/translate/CharSequenceTranslator.java

@@ -58,8 +58,9 @@ public CharSequenceTranslator() {
 
     /**
      * Helper for non-Writer usage.
-     * @param input CharSequence to be translated
-     * @return String output of translation
+     *
+     * @param input CharSequence to be translated.
+     * @return String output of translation.
      */
     public final String translate(final CharSequence input) {
         if (input == null) {
@@ -81,21 +82,21 @@ public final String translate(final CharSequence input) {
      * and the only IOExceptions thrown must be from interacting with the Writer so that
      * the top level API may reliably ignore StringWriter IOExceptions.
      *
-     * @param input CharSequence that is being translated
-     * @param index int representing the current point of translation
-     * @param writer Writer to translate the text to
-     * @return int count of code points consumed
-     * @throws IOException if and only if the Writer produces an IOException
+     * @param input CharSequence that is being translated.
+     * @param index int representing the current point of translation.
+     * @param writer Writer to translate the text to.
+     * @return int count of code points consumed.
+     * @throws IOException if and only if the Writer produces an IOException.
      */
     public abstract int translate(CharSequence input, int index, Writer writer) throws IOException;
 
     /**
      * Translate an input onto a Writer. This is intentionally final as its algorithm is
      * tightly coupled with the abstract method of this class.
      *
-     * @param input CharSequence that is being translated
-     * @param writer Writer to translate the text to
-     * @throws IOException if and only if the Writer produces an IOException
+     * @param input CharSequence that is being translated.
+     * @param writer Writer to translate the text to.
+     * @throws IOException if and only if the Writer produces an IOException.
      */
     public final void translate(final CharSequence input, final Writer writer) throws IOException {
         Validate.isTrue(writer != null, "The Writer must not be null");
@@ -133,8 +134,8 @@ public final void translate(final CharSequence input, final Writer writer) throw
      * Helper method to create a merger of this translator with another set of
      * translators. Useful in customizing the standard functionality.
      *
-     * @param translators CharSequenceTranslator array of translators to merge with this one
-     * @return CharSequenceTranslator merging this translator with the others
+     * @param translators CharSequenceTranslator array of translators to merge with this one.
+     * @return CharSequenceTranslator merging this translator with the others.
      */
     public final CharSequenceTranslator with(final CharSequenceTranslator... translators) {
         final CharSequenceTranslator[] newArray = new CharSequenceTranslator[translators.length + 1];

src/main/java/org/apache/commons/text/translate/CodePointTranslator.java

@@ -44,10 +44,10 @@ public final int translate(final CharSequence input, final int index, final Writ
     /**
      * Translates the specified code point into another.
      *
-     * @param codePoint int character input to translate
-     * @param writer Writer to optionally push the translated output to
-     * @return boolean as to whether translation occurred or not
-     * @throws IOException if and only if the Writer produces an IOException
+     * @param codePoint int character input to translate.
+     * @param writer Writer to optionally push the translated output to.
+     * @return boolean as to whether translation occurred or not.
+     * @throws IOException if and only if the Writer produces an IOException.
      */
     public abstract boolean translate(int codePoint, Writer writer) throws IOException;
 

src/main/java/org/apache/commons/text/translate/EntityArrays.java

@@ -440,8 +440,8 @@ public class EntityArrays {
     /**
      * Inverts an escape Map into an unescape Map.
      *
-     * @param map Map<String, String> to be inverted
-     * @return Map<String, String> inverted array
+     * @param map Map<String, String> to be inverted.
+     * @return Map<String, String> inverted array.
      */
     public static Map<CharSequence, CharSequence> invert(final Map<CharSequence, CharSequence> map) {
         return map.entrySet().stream().collect(Collectors.toMap(Entry::getValue, Entry::getKey));

src/main/java/org/apache/commons/text/translate/JavaUnicodeEscaper.java

@@ -14,6 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.apache.commons.text.translate;
 
 /**
@@ -26,9 +27,8 @@ public class JavaUnicodeEscaper extends UnicodeEscaper {
     /**
      * Constructs a {@code JavaUnicodeEscaper} above the specified value (exclusive).
      *
-     * @param codePoint
-     *            above which to escape
-     * @return The newly created {@code UnicodeEscaper} instance
+     * @param codePoint above which to escape.
+     * @return The newly created {@code UnicodeEscaper} instance.
      */
     public static JavaUnicodeEscaper above(final int codePoint) {
         return outsideOf(0, codePoint);
@@ -37,9 +37,8 @@ public static JavaUnicodeEscaper above(final int codePoint) {
     /**
      * Constructs a {@code JavaUnicodeEscaper} below the specified value (exclusive).
      *
-     * @param codePoint
-     *            below which to escape
-     * @return The newly created {@code UnicodeEscaper} instance
+     * @param codePoint below which to escape.
+     * @return The newly created {@code UnicodeEscaper} instance.
      */
     public static JavaUnicodeEscaper below(final int codePoint) {
         return outsideOf(codePoint, Integer.MAX_VALUE);
@@ -48,11 +47,9 @@ public static JavaUnicodeEscaper below(final int codePoint) {
     /**
      * Constructs a {@code JavaUnicodeEscaper} between the specified values (inclusive).
      *
-     * @param codePointLow
-     *            above which to escape
-     * @param codePointHigh
-     *            below which to escape
-     * @return The newly created {@code UnicodeEscaper} instance
+     * @param codePointLow  above which to escape.
+     * @param codePointHigh below which to escape.
+     * @return The newly created {@code UnicodeEscaper} instance.
      */
     public static JavaUnicodeEscaper between(final int codePointLow, final int codePointHigh) {
         return new JavaUnicodeEscaper(codePointLow, codePointHigh, true);
@@ -61,27 +58,21 @@ public static JavaUnicodeEscaper between(final int codePointLow, final int codeP
     /**
      * Constructs a {@code JavaUnicodeEscaper} outside of the specified values (exclusive).
      *
-     * @param codePointLow
-     *            below which to escape
-     * @param codePointHigh
-     *            above which to escape
-     * @return The newly created {@code UnicodeEscaper} instance
+     * @param codePointLow  below which to escape.
+     * @param codePointHigh above which to escape.
+     * @return The newly created {@code UnicodeEscaper} instance.
      */
     public static JavaUnicodeEscaper outsideOf(final int codePointLow, final int codePointHigh) {
         return new JavaUnicodeEscaper(codePointLow, codePointHigh, false);
     }
 
     /**
-     * Constructs a {@code JavaUnicodeEscaper} for the specified range. This is the underlying method for the
-     * other constructors/builders. The {@code below} and {@code above} boundaries are inclusive when
-     * {@code between} is {@code true} and exclusive when it is {@code false}.
+     * Constructs a {@code JavaUnicodeEscaper} for the specified range. This is the underlying method for the other constructors/builders. The {@code below} and
+     * {@code above} boundaries are inclusive when {@code between} is {@code true} and exclusive when it is {@code false}.
      *
-     * @param below
-     *            int value representing the lowest code point boundary
-     * @param above
-     *            int value representing the highest code point boundary
-     * @param between
-     *            whether to escape between the boundaries or outside them
+     * @param below   int value representing the lowest code point boundary.
+     * @param above   int value representing the highest code point boundary.
+     * @param between whether to escape between the boundaries or outside them.
      */
     public JavaUnicodeEscaper(final int below, final int above, final boolean between) {
         super(below, above, between);
@@ -90,14 +81,12 @@ public JavaUnicodeEscaper(final int below, final int above, final boolean betwee
     /**
      * Converts the given code point to a hexadecimal string of the form {@code "\\uXXXX\\uXXXX"}.
      *
-     * @param codePoint
-     *            a Unicode code point
-     * @return The hexadecimal string for the given code point
+     * @param codePoint a Unicode code point.
+     * @return The hexadecimal string for the given code point.
      */
     @Override
     protected String toUtf16Escape(final int codePoint) {
         final char[] surrogatePair = Character.toChars(codePoint);
         return "\\u" + hex(surrogatePair[0]) + "\\u" + hex(surrogatePair[1]);
     }
-
 }

src/main/java/org/apache/commons/text/translate/LookupTranslator.java

@@ -42,9 +42,10 @@ public class LookupTranslator extends CharSequenceTranslator {
 
     /**
      * Constructs the lookup table to be used in translation.
-     *
+     * <p>
      * Note that, as of Lang 3.1 (the origin of this code), the key to the lookup table is converted to a {@link String}. This is because we need the key to
      * support hashCode and equals(Object), allowing it to be the key for a HashMap. See LANG-882.
+     * </p>
      *
      * @param lookupMap Map&lt;CharSequence, CharSequence&gt; table of translator mappings, may not be null.
      */

src/main/java/org/apache/commons/text/translate/NumericEntityEscaper.java

@@ -31,8 +31,8 @@ public class NumericEntityEscaper extends CodePointTranslator {
     /**
      * Constructs a {@code NumericEntityEscaper} above the specified value (exclusive).
      *
-     * @param codePoint above which to escape
-     * @return The newly created {@code NumericEntityEscaper} instance
+     * @param codePoint above which to escape.
+     * @return The newly created {@code NumericEntityEscaper} instance.
      */
     public static NumericEntityEscaper above(final int codePoint) {
         return outsideOf(0, codePoint);
@@ -41,8 +41,8 @@ public static NumericEntityEscaper above(final int codePoint) {
     /**
      * Constructs a {@code NumericEntityEscaper} below the specified value (exclusive).
      *
-     * @param codePoint below which to escape
-     * @return The newly created {@code NumericEntityEscaper} instance
+     * @param codePoint below which to escape.
+     * @return The newly created {@code NumericEntityEscaper} instance.
      */
     public static NumericEntityEscaper below(final int codePoint) {
         return outsideOf(codePoint, Integer.MAX_VALUE);
@@ -51,9 +51,9 @@ public static NumericEntityEscaper below(final int codePoint) {
     /**
      * Constructs a {@code NumericEntityEscaper} between the specified values (inclusive).
      *
-     * @param codePointLow above which to escape
-     * @param codePointHigh below which to escape
-     * @return The newly created {@code NumericEntityEscaper} instance
+     * @param codePointLow above which to escape.
+     * @param codePointHigh below which to escape.
+     * @return The newly created {@code NumericEntityEscaper} instance.
      */
     public static NumericEntityEscaper between(final int codePointLow, final int codePointHigh) {
         return new NumericEntityEscaper(codePointLow, codePointHigh, true);
@@ -62,9 +62,9 @@ public static NumericEntityEscaper between(final int codePointLow, final int cod
     /**
      * Constructs a {@code NumericEntityEscaper} outside of the specified values (exclusive).
      *
-     * @param codePointLow below which to escape
-     * @param codePointHigh above which to escape
-     * @return The newly created {@code NumericEntityEscaper} instance
+     * @param codePointLow below which to escape.
+     * @param codePointHigh above which to escape.
+     * @return The newly created {@code NumericEntityEscaper} instance.
      */
     public static NumericEntityEscaper outsideOf(final int codePointLow, final int codePointHigh) {
         return new NumericEntityEscaper(codePointLow, codePointHigh, false);
@@ -89,9 +89,9 @@ public NumericEntityEscaper() {
      * and {@code above} boundaries are inclusive when {@code between} is
      * {@code true} and exclusive when it is {@code false}.
      *
-     * @param below int value representing the lowest code point boundary
-     * @param above int value representing the highest code point boundary
-     * @param between whether to escape between the boundaries or outside them
+     * @param below int value representing the lowest code point boundary.
+     * @param above int value representing the highest code point boundary.
+     * @param between whether to escape between the boundaries or outside them.
      */
     private NumericEntityEscaper(final int below, final int above, final boolean between) {
         this.range = Range.of(below, above);

src/main/java/org/apache/commons/text/translate/NumericEntityUnescaper.java

@@ -63,16 +63,25 @@ public enum OPTION {
     /**
      * Creates a UnicodeUnescaper.
      *
-     * The constructor takes a list of options, only one type of which is currently
-     * available (whether to allow, error or ignore the semicolon on the end of a
+     * The constructor takes a list of options, only one type of which is currently available (whether to allow, error or ignore the semicolon on the end of a
      * numeric entity to being missing).
-     *
+     * <p>
      * For example, to support numeric entities without a ';':
-     *    new NumericEntityUnescaper(NumericEntityUnescaper.OPTION.semiColonOptional)
+     * </p>
+     *
+     * <pre>
+     * new NumericEntityUnescaper(NumericEntityUnescaper.OPTION.semiColonOptional)
+     * </pre>
+     * <p>
      * and to throw an IllegalArgumentException when they're missing:
-     *    new NumericEntityUnescaper(NumericEntityUnescaper.OPTION.errorIfNoSemiColon)
+     * </p>
      *
+     * <pre>
+     * new NumericEntityUnescaper(NumericEntityUnescaper.OPTION.errorIfNoSemiColon)
+     * </pre>
+     * <p>
      * Note that the default behavior is to ignore them.
+     * </p>
      *
      * @param options to apply to this unescaper
      */
@@ -83,8 +92,8 @@ public NumericEntityUnescaper(final OPTION... options) {
     /**
      * Tests whether the passed in option is currently set.
      *
-     * @param option to check state of
-     * @return whether the option is set
+     * @param option to check state of.
+     * @return whether the option is set.
      */
     public boolean isSet(final OPTION option) {
         return options.contains(option);

src/main/java/org/apache/commons/text/translate/OctalUnescaper.java

@@ -41,8 +41,8 @@ public OctalUnescaper() {
     /**
      * Tests if the given char is an octal digit. Octal digits are the character representations of the digits 0 to 7.
      *
-     * @param ch the char to check
-     * @return true if the given char is the character representation of one of the digits from 0 to 7
+     * @param ch the char to check.
+     * @return true if the given char is the character representation of one of the digits from 0 to 7.
      */
     private boolean isOctalDigit(final char ch) {
         return ch >= '0' && ch <= '7';
@@ -51,8 +51,8 @@ private boolean isOctalDigit(final char ch) {
     /**
      * Tests if the given char is the character representation of one of the digit from 0 to 3.
      *
-     * @param ch the char to check
-     * @return true if the given char is the character representation of one of the digits from 0 to 3
+     * @param ch the char to check.
+     * @return true if the given char is the character representation of one of the digits from 0 to 3.
      */
     private boolean isZeroToThree(final char ch) {
         return ch >= '0' && ch <= '3';

src/main/java/org/apache/commons/text/translate/SinglePassTranslator.java

@@ -37,7 +37,7 @@ private String getClassName() {
 
     /**
      * {@inheritDoc}
-     * @throws IllegalArgumentException if {@code index != 0}
+     * @throws IllegalArgumentException if {@code index != 0}.
      */
     @Override
     public int translate(final CharSequence input, final int index, final Writer writer) throws IOException {
@@ -54,9 +54,9 @@ public int translate(final CharSequence input, final int index, final Writer wri
     /**
      * Translates whole set of code points passed in input.
      *
-     * @param input CharSequence that is being translated
-     * @param writer Writer to translate the text to
-     * @throws IOException if and only if the Writer produces an IOException
+     * @param input CharSequence that is being translated.
+     * @param writer Writer to translate the text to.
+     * @throws IOException if and only if the Writer produces an IOException.
      */
     abstract void translateWhole(CharSequence input, Writer writer) throws IOException;
 }