Fix Javadoc formatting of org.eclipse.jgit.diff package
Without explicit <p> elements, Javadoc joins all paragraph, resulting in unreadable Javadoc output, e.g. see here: http://download.eclipse.org/jgit/docs/jgit-2.1.0.201209190230-r/apidocs/org/eclipse/jgit/diff/MyersDiff.html Also, <pre> is needed to preserve pre-formatted content. The reflowing of text was automatically done on save. Change-Id: Ia02dd6d759ae066700098e22669ef925e3c813b5
This commit is contained in:
parent
5fc7bd783b
commit
ac81ab4878
|
@ -64,7 +64,7 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Supplies the content of a file for {@link DiffFormatter}.
|
* Supplies the content of a file for {@link DiffFormatter}.
|
||||||
*
|
* <p>
|
||||||
* A content source is not thread-safe. Sources may contain state, including
|
* A content source is not thread-safe. Sources may contain state, including
|
||||||
* information about the last ObjectLoader they returned. Callers must be
|
* information about the last ObjectLoader they returned. Callers must be
|
||||||
* careful to ensure there is no more than one ObjectLoader pending on any
|
* careful to ensure there is no more than one ObjectLoader pending on any
|
||||||
|
|
|
@ -45,7 +45,7 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Compares two {@link Sequence}s to create an {@link EditList} of changes.
|
* Compares two {@link Sequence}s to create an {@link EditList} of changes.
|
||||||
*
|
* <p>
|
||||||
* An algorithm's {@code diff} method must be callable from concurrent threads
|
* An algorithm's {@code diff} method must be callable from concurrent threads
|
||||||
* without data collisions. This permits some algorithms to use a singleton
|
* without data collisions. This permits some algorithms to use a singleton
|
||||||
* pattern, with concurrent invocations using the same singleton. Other
|
* pattern, with concurrent invocations using the same singleton. Other
|
||||||
|
|
|
@ -45,11 +45,11 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Wraps a {@link Sequence} to assign hash codes to elements.
|
* Wraps a {@link Sequence} to assign hash codes to elements.
|
||||||
*
|
* <p>
|
||||||
* This sequence acts as a proxy for the real sequence, caching element hash
|
* This sequence acts as a proxy for the real sequence, caching element hash
|
||||||
* codes so they don't need to be recomputed each time. Sequences of this type
|
* codes so they don't need to be recomputed each time. Sequences of this type
|
||||||
* must be used with a {@link HashedSequenceComparator}.
|
* must be used with a {@link HashedSequenceComparator}.
|
||||||
*
|
* <p>
|
||||||
* To construct an instance of this type use {@link HashedSequencePair}.
|
* To construct an instance of this type use {@link HashedSequencePair}.
|
||||||
*
|
*
|
||||||
* @param <S>
|
* @param <S>
|
||||||
|
|
|
@ -45,11 +45,11 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Wrap another comparator for use with {@link HashedSequence}.
|
* Wrap another comparator for use with {@link HashedSequence}.
|
||||||
*
|
* <p>
|
||||||
* This comparator acts as a proxy for the real comparator, evaluating the
|
* This comparator acts as a proxy for the real comparator, evaluating the
|
||||||
* cached hash code before testing the underlying comparator's equality.
|
* cached hash code before testing the underlying comparator's equality.
|
||||||
* Comparators of this type must be used with a {@link HashedSequence}.
|
* Comparators of this type must be used with a {@link HashedSequence}.
|
||||||
*
|
* <p>
|
||||||
* To construct an instance of this type use {@link HashedSequencePair}.
|
* To construct an instance of this type use {@link HashedSequencePair}.
|
||||||
*
|
*
|
||||||
* @param <S>
|
* @param <S>
|
||||||
|
|
|
@ -45,7 +45,7 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Wraps two {@link Sequence} instances to cache their element hash codes.
|
* Wraps two {@link Sequence} instances to cache their element hash codes.
|
||||||
*
|
* <p>
|
||||||
* This pair wraps two sequences that contain cached hash codes for the input
|
* This pair wraps two sequences that contain cached hash codes for the input
|
||||||
* sequences.
|
* sequences.
|
||||||
*
|
*
|
||||||
|
|
|
@ -45,11 +45,11 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* An extended form of Bram Cohen's patience diff algorithm.
|
* An extended form of Bram Cohen's patience diff algorithm.
|
||||||
*
|
* <p>
|
||||||
* This implementation was derived by using the 4 rules that are outlined in
|
* This implementation was derived by using the 4 rules that are outlined in
|
||||||
* Bram Cohen's <a href="http://bramcohen.livejournal.com/73318.html">blog</a>,
|
* Bram Cohen's <a href="http://bramcohen.livejournal.com/73318.html">blog</a>,
|
||||||
* and then was further extended to support low-occurrence common elements.
|
* and then was further extended to support low-occurrence common elements.
|
||||||
*
|
* <p>
|
||||||
* The basic idea of the algorithm is to create a histogram of occurrences for
|
* The basic idea of the algorithm is to create a histogram of occurrences for
|
||||||
* each element of sequence A. Each element of sequence B is then considered in
|
* each element of sequence A. Each element of sequence B is then considered in
|
||||||
* turn. If the element also exists in sequence A, and has a lower occurrence
|
* turn. If the element also exists in sequence A, and has a lower occurrence
|
||||||
|
@ -58,34 +58,34 @@
|
||||||
* lowest number of occurrences is chosen as a split point. The region is split
|
* lowest number of occurrences is chosen as a split point. The region is split
|
||||||
* around the LCS, and the algorithm is recursively applied to the sections
|
* around the LCS, and the algorithm is recursively applied to the sections
|
||||||
* before and after the LCS.
|
* before and after the LCS.
|
||||||
*
|
* <p>
|
||||||
* By always selecting a LCS position with the lowest occurrence count, this
|
* By always selecting a LCS position with the lowest occurrence count, this
|
||||||
* algorithm behaves exactly like Bram Cohen's patience diff whenever there is a
|
* algorithm behaves exactly like Bram Cohen's patience diff whenever there is a
|
||||||
* unique common element available between the two sequences. When no unique
|
* unique common element available between the two sequences. When no unique
|
||||||
* elements exist, the lowest occurrence element is chosen instead. This offers
|
* elements exist, the lowest occurrence element is chosen instead. This offers
|
||||||
* more readable diffs than simply falling back on the standard Myers' O(ND)
|
* more readable diffs than simply falling back on the standard Myers' O(ND)
|
||||||
* algorithm would produce.
|
* algorithm would produce.
|
||||||
*
|
* <p>
|
||||||
* To prevent the algorithm from having an O(N^2) running time, an upper limit
|
* To prevent the algorithm from having an O(N^2) running time, an upper limit
|
||||||
* on the number of unique elements in a histogram bucket is configured by
|
* on the number of unique elements in a histogram bucket is configured by
|
||||||
* {@link #setMaxChainLength(int)}. If sequence A has more than this many
|
* {@link #setMaxChainLength(int)}. If sequence A has more than this many
|
||||||
* elements that hash into the same hash bucket, the algorithm passes the region
|
* elements that hash into the same hash bucket, the algorithm passes the region
|
||||||
* to {@link #setFallbackAlgorithm(DiffAlgorithm)}. If no fallback algorithm is
|
* to {@link #setFallbackAlgorithm(DiffAlgorithm)}. If no fallback algorithm is
|
||||||
* configured, the region is emitted as a replace edit.
|
* configured, the region is emitted as a replace edit.
|
||||||
*
|
* <p>
|
||||||
* During scanning of sequence B, any element of A that occurs more than
|
* During scanning of sequence B, any element of A that occurs more than
|
||||||
* {@link #setMaxChainLength(int)} times is never considered for an LCS match
|
* {@link #setMaxChainLength(int)} times is never considered for an LCS match
|
||||||
* position, even if it is common between the two sequences. This limits the
|
* position, even if it is common between the two sequences. This limits the
|
||||||
* number of locations in sequence A that must be considered to find the LCS,
|
* number of locations in sequence A that must be considered to find the LCS,
|
||||||
* and helps maintain a lower running time bound.
|
* and helps maintain a lower running time bound.
|
||||||
*
|
* <p>
|
||||||
* So long as {@link #setMaxChainLength(int)} is a small constant (such as 64),
|
* So long as {@link #setMaxChainLength(int)} is a small constant (such as 64),
|
||||||
* the algorithm runs in O(N * D) time, where N is the sum of the input lengths
|
* the algorithm runs in O(N * D) time, where N is the sum of the input lengths
|
||||||
* and D is the number of edits in the resulting EditList. If the supplied
|
* and D is the number of edits in the resulting EditList. If the supplied
|
||||||
* {@link SequenceComparator} has a good hash function, this implementation
|
* {@link SequenceComparator} has a good hash function, this implementation
|
||||||
* typically out-performs {@link MyersDiff}, even though its theoretical running
|
* typically out-performs {@link MyersDiff}, even though its theoretical running
|
||||||
* time is the same.
|
* time is the same.
|
||||||
*
|
* <p>
|
||||||
* This implementation has an internal limitation that prevents it from handling
|
* This implementation has an internal limitation that prevents it from handling
|
||||||
* sequences with more than 268,435,456 (2^28) elements.
|
* sequences with more than 268,435,456 (2^28) elements.
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -47,7 +47,7 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Support {@link HistogramDiff} by computing occurrence counts of elements.
|
* Support {@link HistogramDiff} by computing occurrence counts of elements.
|
||||||
*
|
* <p>
|
||||||
* Each element in the range being considered is put into a hash table, tracking
|
* Each element in the range being considered is put into a hash table, tracking
|
||||||
* the number of times that distinct element appears in the sequence. Once all
|
* the number of times that distinct element appears in the sequence. Once all
|
||||||
* elements have been inserted from sequence A, each element of sequence B is
|
* elements have been inserted from sequence A, each element of sequence B is
|
||||||
|
|
|
@ -51,56 +51,60 @@
|
||||||
import org.eclipse.jgit.util.LongList;
|
import org.eclipse.jgit.util.LongList;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Diff algorithm, based on "An O(ND) Difference Algorithm and its
|
* Diff algorithm, based on "An O(ND) Difference Algorithm and its Variations",
|
||||||
* Variations", by Eugene Myers.
|
* by Eugene Myers.
|
||||||
*
|
* <p>
|
||||||
* The basic idea is to put the line numbers of text A as columns ("x") and the
|
* The basic idea is to put the line numbers of text A as columns ("x") and the
|
||||||
* lines of text B as rows ("y"). Now you try to find the shortest "edit path"
|
* lines of text B as rows ("y"). Now you try to find the shortest "edit path"
|
||||||
* from the upper left corner to the lower right corner, where you can
|
* from the upper left corner to the lower right corner, where you can always go
|
||||||
* always go horizontally or vertically, but diagonally from (x,y) to
|
* horizontally or vertically, but diagonally from (x,y) to (x+1,y+1) only if
|
||||||
* (x+1,y+1) only if line x in text A is identical to line y in text B.
|
* line x in text A is identical to line y in text B.
|
||||||
*
|
* <p>
|
||||||
* Myers' fundamental concept is the "furthest reaching D-path on diagonal k":
|
* Myers' fundamental concept is the "furthest reaching D-path on diagonal k": a
|
||||||
* a D-path is an edit path starting at the upper left corner and containing
|
* D-path is an edit path starting at the upper left corner and containing
|
||||||
* exactly D non-diagonal elements ("differences"). The furthest reaching
|
* exactly D non-diagonal elements ("differences"). The furthest reaching D-path
|
||||||
* D-path on diagonal k is the one that contains the most (diagonal) elements
|
* on diagonal k is the one that contains the most (diagonal) elements which
|
||||||
* which ends on diagonal k (where k = y - x).
|
* ends on diagonal k (where k = y - x).
|
||||||
*
|
* <p>
|
||||||
* Example:
|
* Example:
|
||||||
*
|
*
|
||||||
|
* <pre>
|
||||||
* H E L L O W O R L D
|
* H E L L O W O R L D
|
||||||
* ____
|
* ____
|
||||||
* L \___
|
* L \___
|
||||||
* O \___
|
* O \___
|
||||||
* W \________
|
* W \________
|
||||||
*
|
* </pre>
|
||||||
* Since every D-path has exactly D horizontal or vertical elements, it can
|
* <p>
|
||||||
* only end on the diagonals -D, -D+2, ..., D-2, D.
|
* Since every D-path has exactly D horizontal or vertical elements, it can only
|
||||||
*
|
* end on the diagonals -D, -D+2, ..., D-2, D.
|
||||||
* Since every furthest reaching D-path contains at least one furthest
|
* <p>
|
||||||
* reaching (D-1)-path (except for D=0), we can construct them recursively.
|
* Since every furthest reaching D-path contains at least one furthest reaching
|
||||||
*
|
* (D-1)-path (except for D=0), we can construct them recursively.
|
||||||
|
* <p>
|
||||||
* Since we are really interested in the shortest edit path, we can start
|
* Since we are really interested in the shortest edit path, we can start
|
||||||
* looking for a 0-path, then a 1-path, and so on, until we find a path that
|
* looking for a 0-path, then a 1-path, and so on, until we find a path that
|
||||||
* ends in the lower right corner.
|
* ends in the lower right corner.
|
||||||
*
|
* <p>
|
||||||
* To save space, we do not need to store all paths (which has quadratic space
|
* To save space, we do not need to store all paths (which has quadratic space
|
||||||
* requirements), but generate the D-paths simultaneously from both sides.
|
* requirements), but generate the D-paths simultaneously from both sides. When
|
||||||
* When the ends meet, we will have found "the middle" of the path. From the
|
* the ends meet, we will have found "the middle" of the path. From the end
|
||||||
* end points of that diagonal part, we can generate the rest recursively.
|
* points of that diagonal part, we can generate the rest recursively.
|
||||||
*
|
* <p>
|
||||||
* This only requires linear space.
|
* This only requires linear space.
|
||||||
|
* <p>
|
||||||
|
* The overall (runtime) complexity is:
|
||||||
*
|
*
|
||||||
* The overall (runtime) complexity is
|
* <pre>
|
||||||
*
|
* O(N * D^2 + 2 * N/2 * (D/2)^2 + 4 * N/4 * (D/4)^2 + ...)
|
||||||
* O(N * D^2 + 2 * N/2 * (D/2)^2 + 4 * N/4 * (D/4)^2 + ...)
|
* = O(N * D^2 * 5 / 4) = O(N * D^2),
|
||||||
* = O(N * D^2 * 5 / 4) = O(N * D^2),
|
* </pre>
|
||||||
*
|
* <p>
|
||||||
* (With each step, we have to find the middle parts of twice as many regions
|
* (With each step, we have to find the middle parts of twice as many regions as
|
||||||
* as before, but the regions (as well as the D) are halved.)
|
* before, but the regions (as well as the D) are halved.)
|
||||||
*
|
* <p>
|
||||||
* So the overall runtime complexity stays the same with linear space,
|
* So the overall runtime complexity stays the same with linear space, albeit
|
||||||
* albeit with a larger constant factor.
|
* with a larger constant factor.
|
||||||
*
|
*
|
||||||
* @param <S>
|
* @param <S>
|
||||||
* type of sequence.
|
* type of sequence.
|
||||||
|
|
|
@ -46,15 +46,15 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Arbitrary sequence of elements.
|
* Arbitrary sequence of elements.
|
||||||
*
|
* <p>
|
||||||
* A sequence of elements is defined to contain elements in the index range
|
* A sequence of elements is defined to contain elements in the index range
|
||||||
* <code>[0, {@link #size()})</code>, like a standard Java List implementation.
|
* <code>[0, {@link #size()})</code>, like a standard Java List implementation.
|
||||||
* Unlike a List, the members of the sequence are not directly obtainable.
|
* Unlike a List, the members of the sequence are not directly obtainable.
|
||||||
*
|
* <p>
|
||||||
* Implementations of Sequence are primarily intended for use in content
|
* Implementations of Sequence are primarily intended for use in content
|
||||||
* difference detection algorithms, to produce an {@link EditList} of
|
* difference detection algorithms, to produce an {@link EditList} of
|
||||||
* {@link Edit} instances describing how two Sequence instances differ.
|
* {@link Edit} instances describing how two Sequence instances differ.
|
||||||
*
|
* <p>
|
||||||
* To be compared against another Sequence of the same type, a supporting
|
* To be compared against another Sequence of the same type, a supporting
|
||||||
* {@link SequenceComparator} must also be supplied.
|
* {@link SequenceComparator} must also be supplied.
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -45,11 +45,11 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Equivalence function for a {@link Sequence} compared by difference algorithm.
|
* Equivalence function for a {@link Sequence} compared by difference algorithm.
|
||||||
*
|
* <p>
|
||||||
* Difference algorithms can use a comparator to compare portions of two
|
* Difference algorithms can use a comparator to compare portions of two
|
||||||
* sequences and discover the minimal edits required to transform from one
|
* sequences and discover the minimal edits required to transform from one
|
||||||
* sequence to the other sequence.
|
* sequence to the other sequence.
|
||||||
*
|
* <p>
|
||||||
* Indexes within a sequence are zero-based.
|
* Indexes within a sequence are zero-based.
|
||||||
*
|
*
|
||||||
* @param <S>
|
* @param <S>
|
||||||
|
|
|
@ -45,7 +45,7 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Wraps a {@link Sequence} to have a narrower range of elements.
|
* Wraps a {@link Sequence} to have a narrower range of elements.
|
||||||
*
|
* <p>
|
||||||
* This sequence acts as a proxy for the real sequence, translating element
|
* This sequence acts as a proxy for the real sequence, translating element
|
||||||
* indexes on the fly by adding {@code begin} to them. Sequences of this type
|
* indexes on the fly by adding {@code begin} to them. Sequences of this type
|
||||||
* must be used with a {@link SubsequenceComparator}.
|
* must be used with a {@link SubsequenceComparator}.
|
||||||
|
@ -56,7 +56,7 @@
|
||||||
public final class Subsequence<S extends Sequence> extends Sequence {
|
public final class Subsequence<S extends Sequence> extends Sequence {
|
||||||
/**
|
/**
|
||||||
* Construct a subsequence around the A region/base sequence.
|
* Construct a subsequence around the A region/base sequence.
|
||||||
*
|
*
|
||||||
* @param <S>
|
* @param <S>
|
||||||
* the base sequence type.
|
* the base sequence type.
|
||||||
* @param a
|
* @param a
|
||||||
|
@ -71,7 +71,7 @@ public static <S extends Sequence> Subsequence<S> a(S a, Edit region) {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Construct a subsequence around the B region/base sequence.
|
* Construct a subsequence around the B region/base sequence.
|
||||||
*
|
*
|
||||||
* @param <S>
|
* @param <S>
|
||||||
* the base sequence type.
|
* the base sequence type.
|
||||||
* @param b
|
* @param b
|
||||||
|
@ -86,7 +86,7 @@ public static <S extends Sequence> Subsequence<S> b(S b, Edit region) {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Adjust the Edit to reflect positions in the base sequence.
|
* Adjust the Edit to reflect positions in the base sequence.
|
||||||
*
|
*
|
||||||
* @param <S>
|
* @param <S>
|
||||||
* the base sequence type.
|
* the base sequence type.
|
||||||
* @param e
|
* @param e
|
||||||
|
|
|
@ -45,7 +45,7 @@
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Wrap another comparator for use with {@link Subsequence}.
|
* Wrap another comparator for use with {@link Subsequence}.
|
||||||
*
|
* <p>
|
||||||
* This comparator acts as a proxy for the real comparator, translating element
|
* This comparator acts as a proxy for the real comparator, translating element
|
||||||
* indexes on the fly by adding the subsequence's begin offset to them.
|
* indexes on the fly by adding the subsequence's begin offset to them.
|
||||||
* Comparators of this type must be used with a {@link Subsequence}.
|
* Comparators of this type must be used with a {@link Subsequence}.
|
||||||
|
|
Loading…
Reference in New Issue