Update JavaDoc for DiffUtils class (#163)

mhamadli · web-flow · commit 02532a9720a9 · 2023-03-21T21:54:11.000+01:00
diff --git a/java-diff-utils/src/main/java/com/github/difflib/DiffUtils.java b/java-diff-utils/src/main/java/com/github/difflib/DiffUtils.java
@@ -30,7 +30,7 @@
 import java.util.function.BiPredicate;
 
 /**
- * Implements the difference and patching engine
+ * Utility class to implement the difference and patching engine.
  */
 public final class DiffUtils {
 
@@ -39,38 +39,63 @@ public final class DiffUtils {
      */
     static DiffAlgorithmFactory DEFAULT_DIFF = MyersDiff.factory();
 
+    /**
+     * Sets the default diff algorithm factory to be used by all diff routines.
+     *
+     * @param factory a {@link DiffAlgorithmFactory} represnting the new default diff algorithm factory.
+     */
     public static void withDefaultDiffAlgorithmFactory(DiffAlgorithmFactory factory) {
         DEFAULT_DIFF = factory;
     }
 
     /**
-     * Computes the difference between the original and revised list of elements
-     * with default diff algorithm
+     * Computes the difference between two sequences of elements using the default diff algorithm.
      *
-     * @param <T> types to be diffed
-     * @param original The original text. Must not be {@code null}.
-     * @param revised The revised text. Must not be {@code null}.
-     * @param progress progress listener
-     * @return The patch describing the difference between the original and
-     * revised sequences. Never {@code null}.
+     * @param <T> a generic representing the type of the elements to be compared.
+     * @param original a {@link List} represnting the original sequence of elements. Must not be {@code null}.
+     * @param revised a {@link List} represnting the revised sequence of elements. Must not be {@code null}.
+     * @param progress a {@link DiffAlgorithmListener} represnting the progress listener. Can be {@code null}.
+     * @return The patch describing the difference between the original and revised sequences. Never {@code null}.
      */
     public static <T> Patch<T> diff(List<T> original, List<T> revised, DiffAlgorithmListener progress) {
         return DiffUtils.diff(original, revised, DEFAULT_DIFF.create(), progress);
     }
 
+    /**
+     * Computes the difference between two sequences of elements using the default diff algorithm.
+     *
+     * @param <T> a generic representing the type of the elements to be compared.
+     * @param original a {@link List} represnting the original sequence of elements. Must not be {@code null}.
+     * @param revised a {@link List} represnting the revised sequence of elements. Must not be {@code null}.
+     * @return The patch describing the difference between the original and revised sequences. Never {@code null}.
+     */
     public static <T> Patch<T> diff(List<T> original, List<T> revised) {
         return DiffUtils.diff(original, revised, DEFAULT_DIFF.create(), null);
     }
 
+    /**
+     * Computes the difference between two sequences of elements using the default diff algorithm.
+     *
+     * @param <T> a generic representing the type of the elements to be compared.
+     * @param original a {@link List} represnting the original sequence of elements. Must not be {@code null}.
+     * @param revised a {@link List} represnting the revised sequence of elements. Must not be {@code null}.
+     * @param includeEqualParts a {@link boolean} represnting whether to include equal parts in the resulting patch.
+     * @return The patch describing the difference between the original and revised sequences. Never {@code null}.
+     */
     public static <T> Patch<T> diff(List<T> original, List<T> revised, boolean includeEqualParts) {
         return DiffUtils.diff(original, revised, DEFAULT_DIFF.create(), null, includeEqualParts);
     }
 
     /**
-     * Computes the difference between the original and revised text.
+     * Computes the difference between two strings using the default diff algorithm.
+     *
+     * @param sourceText a {@link String} represnting the original string. Must not be {@code null}.
+     * @param targetText a {@link String} represnting the revised string. Must not be {@code null}.
+     * @param progress a {@link DiffAlgorithmListener} represnting the progress listener. Can be {@code null}.
+     * @return The patch describing the difference between the original and revised strings. Never {@code null}.
      */
     public static Patch<String> diff(String sourceText, String targetText,
-            DiffAlgorithmListener progress) {
+                                     DiffAlgorithmListener progress) {
         return DiffUtils.diff(
                 Arrays.asList(sourceText.split("\n")),
                 Arrays.asList(targetText.split("\n")), progress);
@@ -80,17 +105,16 @@ public static Patch<String> diff(String sourceText, String targetText,
      * Computes the difference between the original and revised list of elements
      * with default diff algorithm
      *
-     * @param source The original text. Must not be {@code null}.
-     * @param target The revised text. Must not be {@code null}.
-     *
-     * @param equalizer the equalizer object to replace the default compare
+     * @param source a {@link List} represnting the original text. Must not be {@code null}.
+     * @param target a {@link List} represnting the revised text. Must not be {@code null}.
+     * @param equalizer a {@link BiPredicate} represnting the equalizer object to replace the default compare
      * algorithm (Object.equals). If {@code null} the default equalizer of the
-     * default algorithm is used..
+     * default algorithm is used.
      * @return The patch describing the difference between the original and
      * revised sequences. Never {@code null}.
      */
     public static <T> Patch<T> diff(List<T> source, List<T> target,
-            BiPredicate<T, T> equalizer) {
+                                    BiPredicate<T, T> equalizer) {
         if (equalizer != null) {
             return DiffUtils.diff(source, target,
                     DEFAULT_DIFF.create(equalizer));
@@ -99,39 +123,40 @@ public static <T> Patch<T> diff(List<T> source, List<T> target,
     }
 
     public static <T> Patch<T> diff(List<T> original, List<T> revised,
-            DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress) {
+                                    DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress) {
         return diff(original, revised, algorithm, progress, false);
     }
 
     /**
      * Computes the difference between the original and revised list of elements
      * with default diff algorithm
      *
-     * @param original The original text. Must not be {@code null}.
-     * @param revised The revised text. Must not be {@code null}.
-     * @param algorithm The diff algorithm. Must not be {@code null}.
-     * @param progress The diff algorithm listener.
+     * @param original a {@link List} represnting the original text. Must not be {@code null}.
+     * @param revised a {@link List} represnting the revised text. Must not be {@code null}.
+     * @param algorithm a {@link DiffAlgorithmI} represnting the diff algorithm. Must not be {@code null}.
+     * @param progress a {@link DiffAlgorithmListener} represnting the diff algorithm listener.
      * @param includeEqualParts Include equal data parts into the patch.
      * @return The patch describing the difference between the original and
      * revised sequences. Never {@code null}.
      */
     public static <T> Patch<T> diff(List<T> original, List<T> revised,
-            DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress,
-            boolean includeEqualParts) {
+                                    DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress,
+                                    boolean includeEqualParts) {
         Objects.requireNonNull(original, "original must not be null");
         Objects.requireNonNull(revised, "revised must not be null");
         Objects.requireNonNull(algorithm, "algorithm must not be null");
 
         return Patch.generate(original, revised, algorithm.computeDiff(original, revised, progress), includeEqualParts);
     }
 
+
     /**
      * Computes the difference between the original and revised list of elements
      * with default diff algorithm
      *
-     * @param original The original text. Must not be {@code null}.
-     * @param revised The revised text. Must not be {@code null}.
-     * @param algorithm The diff algorithm. Must not be {@code null}.
+     * @param original a {@link List} represnting the original text. Must not be {@code null}.
+     * @param revised a {@link List} represnting the revised text. Must not be {@code null}.
+     * @param algorithm a {@link DiffAlgorithmI} represnting the diff algorithm. Must not be {@code null}.
      * @return The patch describing the difference between the original and
      * revised sequences. Never {@code null}.
      */
@@ -144,9 +169,10 @@ public static <T> Patch<T> diff(List<T> original, List<T> revised, DiffAlgorithm
      * "trick" to make out of texts lists of characters, like DiffRowGenerator
      * does and merges those changes at the end together again.
      *
-     * @param original
-     * @param revised
-     * @return
+     * @param original a {@link String} represnting the original text. Must not be {@code null}.
+     * @param revised a {@link String} represnting the revised text. Must not be {@code null}.
+     * @return The patch describing the difference between the original and
+     * revised sequences. Never {@code null}.
      */
     public static Patch<String> diffInline(String original, String revised) {
         List<String> origList = new ArrayList<>();
@@ -165,37 +191,38 @@ public static Patch<String> diffInline(String original, String revised) {
         return patch;
     }
 
-    private static List<String> compressLines(List<String> lines, String delimiter) {
-        if (lines.isEmpty()) {
-            return Collections.emptyList();
-        }
-        return Collections.singletonList(String.join(delimiter, lines));
-    }
-
     /**
-     * Patch the original text with given patch
+     * Applies the given patch to the original list and returns the revised list.
      *
-     * @param original the original text
-     * @param patch the given patch
-     * @return the revised text
-     * @throws PatchFailedException if can't apply patch
+     * @param original a {@link List} represnting the original list.
+     * @param patch a {@link List} represnting the patch to apply.
+     * @return the revised list.
+     * @throws PatchFailedException if the patch cannot be applied.
      */
     public static <T> List<T> patch(List<T> original, Patch<T> patch)
             throws PatchFailedException {
         return patch.applyTo(original);
     }
 
     /**
-     * Unpatch the revised text for a given patch
+     * Applies the given patch to the revised list and returns the original list.
      *
-     * @param revised the revised text
-     * @param patch the given patch
-     * @return the original text
+     * @param revised a {@link List} represnting the revised list.
+     * @param patch a {@link Patch} represnting the patch to apply.
+     * @return the original list.
+     * @throws PatchFailedException if the patch cannot be applied.
      */
     public static <T> List<T> unpatch(List<T> revised, Patch<T> patch) {
         return patch.restore(revised);
     }
 
+    private static List<String> compressLines(List<String> lines, String delimiter) {
+        if (lines.isEmpty()) {
+            return Collections.emptyList();
+        }
+        return Collections.singletonList(String.join(delimiter, lines));
+    }
+
     private DiffUtils() {
     }
 }
