Update JavaDoc to include throws for NPE

Author: paulirwin

src/main/java/info/debatty/java/stringsimilarity/CharacterSubstitutionInterface.java

@@ -37,9 +37,9 @@
 public interface CharacterSubstitutionInterface {
     /**
      * Indicate the cost of substitution c1 and c2.
-     * @param c1
-     * @param c2
-     * @return
+     * @param c1 The first character of the substitution.
+     * @param c2 The second character of the substitution.
+     * @return The cost in the range [0, 1].
      */
     double cost(char c1, char c2);
 }

src/main/java/info/debatty/java/stringsimilarity/Cosine.java

@@ -65,9 +65,10 @@ public Cosine() {
 
     /**
      * Compute the cosine similarity between strings.
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return The cosine similarity in the range [0, 1]
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double similarity(final String s1, final String s2) {
         if (s1 == null) {
@@ -137,9 +138,10 @@ private static double dotProduct(
 
     /**
      * Return 1.0 - similarity.
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return 1.0 - the cosine similarity in the range [0, 1]
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
         return 1.0 - similarity(s1, s2);

src/main/java/info/debatty/java/stringsimilarity/Damerau.java

@@ -50,9 +50,10 @@ public class Damerau implements MetricStringDistance {
      * needed to transform one string into the other (insertion, deletion,
      * substitution of a single character, or a transposition of two adjacent
      * characters).
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return The computed distance.
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
 

src/main/java/info/debatty/java/stringsimilarity/Jaccard.java

@@ -69,10 +69,11 @@ public Jaccard() {
     }
 
     /**
-     * Compute jaccard index: |A inter B| / |A union B|.
-     * @param s1
-     * @param s2
-     * @return
+     * Compute Jaccard index: |A inter B| / |A union B|.
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return The Jaccard index in the range [0, 1]
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double similarity(final String s1, final String s2) {
         if (s1 == null) {
@@ -108,9 +109,10 @@ public final double similarity(final String s1, final String s2) {
 
     /**
      * Distance is computed as 1 - similarity.
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return 1 - the Jaccard similarity.
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
         return 1.0 - similarity(s1, s2);

src/main/java/info/debatty/java/stringsimilarity/JaroWinkler.java

@@ -55,10 +55,11 @@ public final double getThreshold() {
     }
 
     /**
-     * Compute JW similarity.
-     * @param s1
-     * @param s2
-     * @return
+     * Compute Jaro-Winkler similarity.
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return The Jaro-Winkler similarity in the range [0, 1]
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double similarity(final String s1, final String s2) {
         if (s1 == null) {
@@ -91,9 +92,10 @@ public final double similarity(final String s1, final String s2) {
 
     /**
      * Return 1 - similarity.
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return 1 - similarity.
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
         return 1.0 - similarity(s1, s2);

src/main/java/info/debatty/java/stringsimilarity/Levenshtein.java

@@ -33,9 +33,10 @@ public class Levenshtein implements MetricStringDistance {
      * only 2 rows of data. The space requirement is thus O(m) and the algorithm
      * runs in O(mn).
      *
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return The computed Levenshtein distance.
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
         if (s1 == null) {

src/main/java/info/debatty/java/stringsimilarity/LongestCommonSubsequence.java

@@ -30,10 +30,11 @@ public class LongestCommonSubsequence implements StringDistance {
      * Return the LCS distance between strings s1 and s2, computed as |s1| +
      * |s2| - 2 * |LCS(s1, s2)|.
      *
-     * @param s1
-     * @param s2
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
      * @return the LCS distance between strings s1 and s2, computed as |s1| +
      * |s2| - 2 * |LCS(s1, s2)|
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
         if (s1 == null) {
@@ -55,11 +56,20 @@ public final double distance(final String s1, final String s2) {
      * Return the length of Longest Common Subsequence (LCS) between strings s1
      * and s2.
      *
-     * @param s1
-     * @param s2
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
      * @return the length of LCS(s1, s2)
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final int length(final String s1, final String s2) {
+        if (s1 == null) {
+            throw new NullPointerException("s1 must not be null");
+        }
+
+        if (s2 == null) {
+            throw new NullPointerException("s2 must not be null");
+        }
+
         /* function LCSLength(X[1..m], Y[1..n])
          C = array(0..m, 0..n)
 

src/main/java/info/debatty/java/stringsimilarity/MetricLCS.java

@@ -44,9 +44,10 @@ public class MetricLCS
      * Distance metric based on Longest Common Subsequence, computed as
      * 1 - |LCS(s1, s2)| / max(|s1|, |s2|).
      *
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return The computed distance metric value.
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
         if (s1 == null) {
@@ -69,5 +70,4 @@ public final double distance(final String s1, final String s2) {
             - (1.0 * lcs.length(s1, s2))
             / mLen;
     }
-
 }

src/main/java/info/debatty/java/stringsimilarity/NGram.java

@@ -37,9 +37,10 @@ public NGram() {
 
     /**
      * Compute n-gram distance.
-     * @param s0
-     * @param s1
-     * @return
+     * @param s0 The first string to compare.
+     * @param s1 The second string to compare.
+     * @return The computed n-gram distance in the range [0, 1]
+     * @throws NullPointerException if s0 or s1 is null.
      */
     public final double distance(final String s0, final String s1) {
         if (s0 == null) {

src/main/java/info/debatty/java/stringsimilarity/NormalizedLevenshtein.java

@@ -43,9 +43,10 @@ public class NormalizedLevenshtein implements
 
     /**
      * Compute distance as Levenshtein(s1, s2) / max(|s1|, |s2|).
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return The computed distance in the range [0, 1]
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double distance(final String s1, final String s2) {
 
@@ -72,9 +73,10 @@ public final double distance(final String s1, final String s2) {
 
     /**
      * Return 1 - distance.
-     * @param s1
-     * @param s2
-     * @return
+     * @param s1 The first string to compare.
+     * @param s2 The second string to compare.
+     * @return 1.0 - the computed distance
+     * @throws NullPointerException if s1 or s2 is null.
      */
     public final double similarity(final String s1, final String s2) {
         return 1.0 - distance(s1, s2);