Merge branch 'master' into release

Author: garydgregory

src/main/java/org/apache/commons/text/similarity/CosineSimilarity.java

@@ -34,7 +34,7 @@
 public class CosineSimilarity {
 
     /**
-     * Singleton instance.
+     * The singleton instance.
      */
     static final CosineSimilarity INSTANCE = new CosineSimilarity();
 
@@ -48,9 +48,9 @@ public CosineSimilarity() {
     /**
      * Calculates the cosine similarity for two given vectors.
      *
-     * @param leftVector left vector
-     * @param rightVector right vector
-     * @return cosine similarity between the two vectors
+     * @param leftVector left vector.
+     * @param rightVector right vector.
+     * @return cosine similarity between the two vectors.
      */
     public Double cosineSimilarity(final Map<CharSequence, Integer> leftVector,
                                    final Map<CharSequence, Integer> rightVector) {
@@ -83,10 +83,10 @@ public Double cosineSimilarity(final Map<CharSequence, Integer> leftVector,
      * that if a vector is longer than other, then a smaller part of it will be used to compute
      * the dot product.
      *
-     * @param leftVector left vector
-     * @param rightVector right vector
-     * @param intersection common elements
-     * @return The dot product
+     * @param leftVector left vector.
+     * @param rightVector right vector.
+     * @param intersection common elements.
+     * @return The dot product.
      */
     private double dot(final Map<CharSequence, Integer> leftVector, final Map<CharSequence, Integer> rightVector,
             final Set<CharSequence> intersection) {
@@ -100,9 +100,9 @@ private double dot(final Map<CharSequence, Integer> leftVector, final Map<CharSe
     /**
      * Returns a set with keys common to the two given maps.
      *
-     * @param leftVector left vector map
-     * @param rightVector right vector map
-     * @return common strings
+     * @param leftVector left vector map.
+     * @param rightVector right vector map.
+     * @return common strings.
      */
     private Set<CharSequence> getIntersection(final Map<CharSequence, Integer> leftVector,
             final Map<CharSequence, Integer> rightVector) {

src/main/java/org/apache/commons/text/similarity/EditDistanceFrom.java

@@ -80,8 +80,8 @@ public EditDistanceFrom(final EditDistance<R> editDistance, final CharSequence l
      * Compares "left" field against the "right" parameter
      * using the "edit distance" implementation.
      *
-     * @param right the second CharSequence
-     * @return The similarity score between two CharSequences
+     * @param right the second CharSequence.
+     * @return The similarity score between two CharSequences.
      */
     public R apply(final CharSequence right) {
         return editDistance.apply(left, right);
@@ -90,7 +90,7 @@ public R apply(final CharSequence right) {
     /**
      * Gets the edit distance.
      *
-     * @return The edit distance
+     * @return The edit distance.
      */
     public EditDistance<R> getEditDistance() {
         return editDistance;
@@ -99,7 +99,7 @@ public EditDistance<R> getEditDistance() {
     /**
      * Gets the left parameter.
      *
-     * @return The left parameter
+     * @return The left parameter.
      */
     public CharSequence getLeft() {
         return left;

src/main/java/org/apache/commons/text/similarity/FuzzyScore.java

@@ -43,10 +43,8 @@ public class FuzzyScore {
     /**
      * This returns a {@link Locale}-specific {@link FuzzyScore}.
      *
-     * @param locale The string matching logic is case insensitive.
-                     A {@link Locale} is necessary to normalize both Strings to lower case.
-     * @throws IllegalArgumentException
-     *         This is thrown if the {@link Locale} parameter is {@code null}.
+     * @param locale The string matching logic is case insensitive. A {@link Locale} is necessary to normalize both Strings to lower case.
+     * @throws IllegalArgumentException This is thrown if the {@link Locale} parameter is {@code null}.
      */
     public FuzzyScore(final Locale locale) {
         if (locale == null) {
@@ -56,8 +54,7 @@ public FuzzyScore(final Locale locale) {
     }
 
     /**
-     * Find the Fuzzy Score which indicates the similarity score between two
-     * Strings.
+     * Find the Fuzzy Score which indicates the similarity score between two Strings.
      *
      * <pre>
      * score.fuzzyScore(null, null)                          = IllegalArgumentException
@@ -72,11 +69,10 @@ public FuzzyScore(final Locale locale) {
      * score.fuzzyScore("Apache Software Foundation", "asf") = 3
      * </pre>
      *
-     * @param term a full term that should be matched against, must not be null
-     * @param query the query that will be matched against a term, must not be
-     *            null
-     * @return result score
-     * @throws IllegalArgumentException if the term or query is {@code null}
+     * @param term  a full term that should be matched against, must not be null.
+     * @param query the query that will be matched against a term, must not be null.
+     * @return result score.
+     * @throws IllegalArgumentException if the term or query is {@code null}.
      */
     public Integer fuzzyScore(final CharSequence term, final CharSequence query) {
         if (term == null || query == null) {

src/main/java/org/apache/commons/text/similarity/IntersectionResult.java

@@ -49,11 +49,11 @@ public class IntersectionResult {
     /**
      * Constructs the results for an intersection between two sets.
      *
-     * @param sizeA the size of set A ({@code |A|})
-     * @param sizeB the size of set B ({@code |B|})
-     * @param intersection the size of the intersection of A and B ({@code |A ∩ B|})
+     * @param sizeA the size of set A ({@code |A|}).
+     * @param sizeB the size of set B ({@code |B|}).
+     * @param intersection the size of the intersection of A and B ({@code |A ∩ B|}).
      * @throws IllegalArgumentException if the sizes are negative or the intersection is greater
-     * than the minimum of the two set sizes
+     * than the minimum of the two set sizes.
      */
     public IntersectionResult(final int sizeA, final int sizeB, final int intersection) {
         if (sizeA < 0) {

src/main/java/org/apache/commons/text/similarity/IntersectionSimilarity.java

@@ -82,7 +82,7 @@ private TinyBag(final int initialCapacity) {
         /**
          * Adds a new element to the bag, incrementing its count in the underlying map.
          *
-         * @param object the object to add
+         * @param object the object to add.
          */
         private void add(final T object) {
             map.computeIfAbsent(object, k -> new BagCount()).count++;
@@ -91,7 +91,7 @@ private void add(final T object) {
         /**
          * Returns a Set view of the mappings contained in this bag.
          *
-         * @return The Set view
+         * @return The Set view.
          */
         private Set<Entry<T, BagCount>> entrySet() {
             return map.entrySet();
@@ -101,8 +101,8 @@ private Set<Entry<T, BagCount>> entrySet() {
          * Returns the number of occurrence of the given element in this bag by
          * looking up its count in the underlying map.
          *
-         * @param object the object to search for
-         * @return The number of occurrences of the object, zero if not found
+         * @param object the object to search for.
+         * @return The number of occurrences of the object, zero if not found.
          */
         private int getCount(final Object object) {
             return map.getOrDefault(object, BagCount.ZERO).count;
@@ -111,7 +111,7 @@ private int getCount(final Object object) {
         /**
          * Gets the number of unique elements in the bag.
          *
-         * @return The unique element size
+         * @return The unique element size.
          */
         private int uniqueElementSize() {
             return map.size();
@@ -122,10 +122,10 @@ private int uniqueElementSize() {
      * Computes the intersection between two sets. This is the count of all the elements
      * that are within both sets.
      *
-     * @param <T> the type of the elements in the set
-     * @param setA the set A
-     * @param setB the set B
-     * @return The intersection
+     * @param <T> the type of the elements in the set.
+     * @param setA the set A.
+     * @param setB the set B.
+     * @return The intersection of A and B.
      */
     private static <T> int getIntersection(final Set<T> setA, final Set<T> setB) {
         int intersection = 0;
@@ -149,8 +149,8 @@ private static <T> int getIntersection(final Set<T> setA, final Set<T> setB) {
      * that will include duplicates in the intersect and union.
      * </p>
      *
-     * @param converter the converter used to create the elements from the characters
-     * @throws IllegalArgumentException if the converter is null
+     * @param converter the converter used to create the elements from the characters.
+     * @throws IllegalArgumentException if the converter is null.
      */
     public IntersectionSimilarity(final Function<CharSequence, Collection<T>> converter) {
         if (converter == null) {
@@ -162,10 +162,10 @@ public IntersectionSimilarity(final Function<CharSequence, Collection<T>> conver
     /**
      * Calculates the intersection of two character sequences passed as input.
      *
-     * @param left first character sequence
-     * @param right second character sequence
-     * @return The intersection result
-     * @throws IllegalArgumentException if either input sequence is {@code null}
+     * @param left first character sequence.
+     * @param right second character sequence.
+     * @return The intersection result.
+     * @throws IllegalArgumentException if either input sequence is {@code null}.
      */
     @Override
     public IntersectionResult apply(final CharSequence left, final CharSequence right) {
@@ -210,9 +210,9 @@ public IntersectionResult apply(final CharSequence left, final CharSequence righ
      * Computes the intersection between two bags. This is the sum of the minimum
      * count of each element that is within both sets.
      *
-     * @param bagA the bag A
-     * @param bagB the bag B
-     * @return The intersection
+     * @param bagA the bag A.
+     * @param bagB the bag B.
+     * @return The intersection of A and B.
      */
     private int getIntersection(final TinyBag bagA, final TinyBag bagB) {
         int intersection = 0;
@@ -229,8 +229,8 @@ private int getIntersection(final TinyBag bagA, final TinyBag bagB) {
      * Converts the collection to a bag. The bag will contain the count of each element
      * in the collection.
      *
-     * @param objects the objects
-     * @return The bag
+     * @param objects the objects.
+     * @return The bag.
      */
     private TinyBag toBag(final Collection<T> objects) {
         final TinyBag bag = new TinyBag(objects.size());

src/main/java/org/apache/commons/text/similarity/JaccardDistance.java

@@ -40,7 +40,7 @@ public JaccardDistance() {
      *
      * @param left  first input sequence.
      * @param right second input sequence.
-     * @return index
+     * @return The Jaccard distance.
      * @throws IllegalArgumentException if either String input {@code null}.
      */
     @Override
@@ -54,7 +54,7 @@ public Double apply(final CharSequence left, final CharSequence right) {
      * @param <E>   The type of similarity score unit.
      * @param left  first input sequence.
      * @param right second input sequence.
-     * @return index
+     * @return index.
      * @throws IllegalArgumentException if either String input {@code null}.
      */
     public <E> Double apply(final SimilarityInput<E> left, final SimilarityInput<E> right) {

src/main/java/org/apache/commons/text/similarity/JaccardSimilarity.java

@@ -32,7 +32,7 @@
 public class JaccardSimilarity implements SimilarityScore<Double> {
 
     /**
-     * Singleton instance.
+     * The singleton instance.
      */
     static final JaccardSimilarity INSTANCE = new JaccardSimilarity();
 
@@ -48,7 +48,7 @@ public JaccardSimilarity() {
      *
      * @param left  first input sequence.
      * @param right second input sequence.
-     * @return index.
+     * @return The Jaccard Similarity of two set character sequence passed as input.
      * @throws IllegalArgumentException if either String input {@code null}.
      */
     @Override
@@ -63,7 +63,7 @@ public Double apply(final CharSequence left, final CharSequence right) {
      * @param <E>   The type of similarity score unit.
      * @param left  first input sequence.
      * @param right second input sequence.
-     * @return index.
+     * @return The Jaccard Similarity of two set character sequence passed as input.
      * @since 1.13.0
      */
     public <E> Double apply(final SimilarityInput<E> left, final SimilarityInput<E> right) {

src/main/java/org/apache/commons/text/similarity/JaroWinklerDistance.java

@@ -81,7 +81,7 @@ public JaroWinklerDistance() {
      * @param left the first input, must not be null.
      * @param right the second input, must not be null.
      * @return result distance.
-     * @throws IllegalArgumentException if either CharSequence input is {@code null}
+     * @throws IllegalArgumentException if either CharSequence input is {@code null}.
      */
     @Override
     public Double apply(final CharSequence left, final CharSequence right) {

src/main/java/org/apache/commons/text/similarity/JaroWinklerSimilarity.java

@@ -39,7 +39,7 @@
 public class JaroWinklerSimilarity implements SimilarityScore<Double> {
 
     /**
-     * Singleton instance.
+     * The singleton instance.
      */
     static final JaroWinklerSimilarity INSTANCE = new JaroWinklerSimilarity();