From 4bbc4c9bd7ae9262a93aa5cfe3f225cb92fc9705 Mon Sep 17 00:00:00 2001 From: Al Salti Date: Sun, 12 Mar 2023 15:14:04 +0300 Subject: [PATCH] Update JavaDoc for DiffUtils class --- .../java/com/github/difflib/DiffUtils.java | 119 +++++++++++------- 1 file changed, 73 insertions(+), 46 deletions(-) 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 index 493d905b..8917772b 100644 --- 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 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 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 Patch diff(List original, List 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 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 Patch diff(List original, List revised) { return DiffUtils.diff(original, revised, DEFAULT_DIFF.create(), null); } + /** + * Computes the difference between two sequences of elements using the default diff algorithm. + * + * @param 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 Patch diff(List original, List 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 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 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 Patch diff(List source, List target, - BiPredicate equalizer) { + BiPredicate equalizer) { if (equalizer != null) { return DiffUtils.diff(source, target, DEFAULT_DIFF.create(equalizer)); @@ -99,7 +123,7 @@ public static Patch diff(List source, List target, } public static Patch diff(List original, List revised, - DiffAlgorithmI algorithm, DiffAlgorithmListener progress) { + DiffAlgorithmI algorithm, DiffAlgorithmListener progress) { return diff(original, revised, algorithm, progress, false); } @@ -107,17 +131,17 @@ public static Patch diff(List original, List revised, * 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 Patch diff(List original, List revised, - DiffAlgorithmI algorithm, DiffAlgorithmListener progress, - boolean includeEqualParts) { + DiffAlgorithmI 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"); @@ -125,13 +149,14 @@ public static Patch diff(List original, List revised, 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 Patch diff(List original, List 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 diffInline(String original, String revised) { List origList = new ArrayList<>(); @@ -165,20 +191,13 @@ public static Patch diffInline(String original, String revised) { return patch; } - private static List compressLines(List 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 List patch(List original, Patch patch) throws PatchFailedException { @@ -186,16 +205,24 @@ public static List patch(List original, Patch patch) } /** - * 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 List unpatch(List revised, Patch patch) { return patch.restore(revised); } + private static List compressLines(List lines, String delimiter) { + if (lines.isEmpty()) { + return Collections.emptyList(); + } + return Collections.singletonList(String.join(delimiter, lines)); + } + private DiffUtils() { } }