From 23f3b6ab246eee1ce73a98fd515f60d5f5135940 Mon Sep 17 00:00:00 2001 From: Matthias Sohn Date: Mon, 18 Dec 2017 23:45:58 +0100 Subject: [PATCH] Fix javadoc in org.eclipse.jgit patch and revplot package Change-Id: I6f1aba98bf7034cb51494c546806cf1b72dd1473 Signed-off-by: Matthias Sohn --- .../org/eclipse/jgit/patch/BinaryHunk.java | 40 +++++++++-- .../jgit/patch/CombinedFileHeader.java | 34 +++++++--- .../jgit/patch/CombinedHunkHeader.java | 6 +- .../org/eclipse/jgit/patch/FileHeader.java | 68 +++++++++++++++---- .../org/eclipse/jgit/patch/FormatError.java | 35 ++++++++-- .../org/eclipse/jgit/patch/HunkHeader.java | 59 +++++++++++++--- .../src/org/eclipse/jgit/patch/Patch.java | 23 +++++-- .../org/eclipse/jgit/revplot/PlotCommit.java | 5 +- .../eclipse/jgit/revplot/PlotCommitList.java | 16 +++-- .../org/eclipse/jgit/revplot/PlotWalk.java | 11 ++- 10 files changed, 236 insertions(+), 61 deletions(-) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java index d0a6b1f318..079d6f6d67 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/BinaryHunk.java @@ -49,7 +49,9 @@ import static org.eclipse.jgit.util.RawParseUtils.match; import static org.eclipse.jgit.util.RawParseUtils.nextLF; import static org.eclipse.jgit.util.RawParseUtils.parseBase10; -/** Part of a "GIT binary patch" to describe the pre-image or post-image */ +/** + * Part of a "GIT binary patch" to describe the pre-image or post-image + */ public class BinaryHunk { private static final byte[] LITERAL = encodeASCII("literal "); //$NON-NLS-1$ @@ -83,32 +85,56 @@ public class BinaryHunk { startOffset = offset; } - /** @return header for the file this hunk applies to */ + /** + * Get header for the file this hunk applies to. + * + * @return header for the file this hunk applies to. + */ public FileHeader getFileHeader() { return file; } - /** @return the byte array holding this hunk's patch script. */ + /** + * Get the byte array holding this hunk's patch script. + * + * @return the byte array holding this hunk's patch script. + */ public byte[] getBuffer() { return file.buf; } - /** @return offset the start of this hunk in {@link #getBuffer()}. */ + /** + * Get offset the start of this hunk in {@link #getBuffer()}. + * + * @return offset the start of this hunk in {@link #getBuffer()}. + */ public int getStartOffset() { return startOffset; } - /** @return offset one past the end of the hunk in {@link #getBuffer()}. */ + /** + * Get offset one past the end of the hunk in {@link #getBuffer()}. + * + * @return offset one past the end of the hunk in {@link #getBuffer()}. + */ public int getEndOffset() { return endOffset; } - /** @return type of this binary hunk */ + /** + * Get type of this binary hunk. + * + * @return type of this binary hunk. + */ public Type getType() { return type; } - /** @return inflated size of this hunk's data */ + /** + * Get inflated size of this hunk's data. + * + * @return inflated size of this hunk's data. + */ public int getSize() { return length; } diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java index 2c8f34e7cd..1afb53da8e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedFileHeader.java @@ -73,19 +73,29 @@ public class CombinedFileHeader extends FileHeader { super(b, offset); } + /** {@inheritDoc} */ @Override @SuppressWarnings("unchecked") public List getHunks() { return (List) super.getHunks(); } - /** @return number of ancestor revisions mentioned in this diff. */ + /** + * {@inheritDoc} + *

+ * + * @return number of ancestor revisions mentioned in this diff. + */ @Override public int getParentCount() { return oldIds.length; } - /** @return get the file mode of the first parent. */ + /** + * {@inheritDoc} + *

+ * @return get the file mode of the first parent. + */ @Override public FileMode getOldMode() { return getOldMode(0); @@ -102,7 +112,12 @@ public class CombinedFileHeader extends FileHeader { return oldModes[nthParent]; } - /** @return get the object id of the first parent. */ + /** + * {@inheritDoc} + *

+ * + * @return get the object id of the first parent. + */ @Override public AbbreviatedObjectId getOldId() { return getOldId(0); @@ -119,6 +134,7 @@ public class CombinedFileHeader extends FileHeader { return oldIds[nthParent]; } + /** {@inheritDoc} */ @Override public String getScriptText(final Charset ocs, final Charset ncs) { final Charset[] cs = new Charset[getParentCount() + 1]; @@ -128,15 +144,9 @@ public class CombinedFileHeader extends FileHeader { } /** + * {@inheritDoc} + *

* Convert the patch script for this file into a string. - * - * @param charsetGuess - * optional array to suggest the character set to use when - * decoding each file's line. If supplied the array must have a - * length of {@link #getParentCount()} + 1 - * representing the old revision character sets and the new - * revision character set. - * @return the patch script, as a Unicode string. */ @Override public String getScriptText(final Charset[] charsetGuess) { @@ -179,6 +189,7 @@ public class CombinedFileHeader extends FileHeader { return ptr; } + /** {@inheritDoc} */ @Override protected void parseIndexLine(int ptr, final int eol) { // "index $asha1,$bsha1..$csha1" @@ -200,6 +211,7 @@ public class CombinedFileHeader extends FileHeader { oldModes = new FileMode[oldIds.length]; } + /** {@inheritDoc} */ @Override protected void parseNewFileMode(final int ptr, final int eol) { for (int i = 0; i < oldModes.length; i++) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java index ed79787291..bbf802317d 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/CombinedHunkHeader.java @@ -54,7 +54,9 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AbbreviatedObjectId; import org.eclipse.jgit.util.MutableInteger; -/** Hunk header for a hunk appearing in a "diff --cc" style patch. */ +/** + * Hunk header for a hunk appearing in a "diff --cc" style patch. + */ public class CombinedHunkHeader extends HunkHeader { private static abstract class CombinedOldImage extends OldImage { int nContext; @@ -76,11 +78,13 @@ public class CombinedHunkHeader extends HunkHeader { } } + /** {@inheritDoc} */ @Override public CombinedFileHeader getFileHeader() { return (CombinedFileHeader) super.getFileHeader(); } + /** {@inheritDoc} */ @Override public OldImage getOldImage() { return getOldImage(0); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java index eb28a0e2a3..5cfbbb2d88 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FileHeader.java @@ -69,7 +69,9 @@ import org.eclipse.jgit.util.QuotedString; import org.eclipse.jgit.util.RawParseUtils; import org.eclipse.jgit.util.TemporaryBuffer; -/** Patch header describing an action for a single file path. */ +/** + * Patch header describing an action for a single file path. + */ public class FileHeader extends DiffEntry { private static final byte[] OLD_MODE = encodeASCII("old mode "); //$NON-NLS-1$ @@ -164,17 +166,30 @@ public class FileHeader extends DiffEntry { return 1; } - /** @return the byte array holding this file's patch script. */ + /** + * Get the byte array holding this file's patch script. + * + * @return the byte array holding this file's patch script. + */ public byte[] getBuffer() { return buf; } - /** @return offset the start of this file's script in {@link #getBuffer()}. */ + /** + * Get offset of the start of this file's script in {@link #getBuffer()}. + * + * @return offset of the start of this file's script in + * {@link #getBuffer()}. + */ public int getStartOffset() { return startOffset; } - /** @return offset one past the end of the file script. */ + /** + * Get offset one past the end of the file script. + * + * @return offset one past the end of the file script. + */ public int getEndOffset() { return endOffset; } @@ -182,8 +197,9 @@ public class FileHeader extends DiffEntry { /** * Convert the patch script for this file into a string. *

- * The default character encoding ({@link Constants#CHARSET}) is assumed for - * both the old and new files. + * The default character encoding + * ({@link org.eclipse.jgit.lib.Constants#CHARSET}) is assumed for both the + * old and new files. * * @return the patch script, as a Unicode string. */ @@ -284,17 +300,29 @@ public class FileHeader extends DiffEntry { } } - /** @return style of patch used to modify this file */ + /** + * Get style of patch used to modify this file. + * + * @return style of patch used to modify this file. + */ public PatchType getPatchType() { return patchType; } - /** @return true if this patch modifies metadata about a file */ + /** + * Whether this patch modifies metadata about a file + * + * @return {@code true} if this patch modifies metadata about a file . + */ public boolean hasMetaDataChanges() { return changeType != ChangeType.MODIFY || newMode != oldMode; } - /** @return hunks altering this file; in order of appearance in patch */ + /** + * Get hunks altering this file; in order of appearance in patch + * + * @return hunks altering this file; in order of appearance in patch. + */ public List getHunks() { if (hunks == null) return Collections.emptyList(); @@ -313,17 +341,33 @@ public class FileHeader extends DiffEntry { return new HunkHeader(this, offset); } - /** @return if a {@link PatchType#GIT_BINARY}, the new-image delta/literal */ + /** + * Get the new-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + * + * @return the new-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + */ public BinaryHunk getForwardBinaryHunk() { return forwardBinaryHunk; } - /** @return if a {@link PatchType#GIT_BINARY}, the old-image delta/literal */ + /** + * Get the old-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + * + * @return the old-image delta/literal if this is a + * {@link PatchType#GIT_BINARY}. + */ public BinaryHunk getReverseBinaryHunk() { return reverseBinaryHunk; } - /** @return a list describing the content edits performed on this file. */ + /** + * Convert to a list describing the content edits performed on this file. + * + * @return a list describing the content edits performed on this file. + */ public EditList toEditList() { final EditList r = new EditList(); for (final HunkHeader hunk : hunks) diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java index 767cb24306..1dd24d732e 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/FormatError.java @@ -48,7 +48,9 @@ import java.util.Locale; import org.eclipse.jgit.lib.Constants; import org.eclipse.jgit.util.RawParseUtils; -/** An error in a patch script */ +/** + * An error in a patch script + */ public class FormatError { /** Classification of an error. */ public static enum Severity { @@ -75,32 +77,53 @@ public class FormatError { message = msg; } - /** @return the severity of the error. */ + /** + * Get the severity of the error. + * + * @return the severity of the error. + */ public Severity getSeverity() { return severity; } - /** @return a message describing the error. */ + /** + * Get a message describing the error. + * + * @return a message describing the error. + */ public String getMessage() { return message; } - /** @return the byte buffer holding the patch script. */ + /** + * Get the byte buffer holding the patch script. + * + * @return the byte buffer holding the patch script. + */ public byte[] getBuffer() { return buf; } - /** @return byte offset within {@link #getBuffer()} where the error is */ + /** + * Get byte offset within {@link #getBuffer()} where the error is. + * + * @return byte offset within {@link #getBuffer()} where the error is. + */ public int getOffset() { return offset; } - /** @return line of the patch script the error appears on. */ + /** + * Get line of the patch script the error appears on. + * + * @return line of the patch script the error appears on. + */ public String getLineText() { final int eol = RawParseUtils.nextLF(buf, offset); return RawParseUtils.decode(Constants.CHARSET, buf, offset, eol); } + /** {@inheritDoc} */ @Override public String toString() { final StringBuilder r = new StringBuilder(); diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java index d72b9bb83a..d022d47833 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/HunkHeader.java @@ -57,7 +57,9 @@ import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.lib.AbbreviatedObjectId; import org.eclipse.jgit.util.MutableInteger; -/** Hunk header describing the layout of a single block of lines */ +/** + * Hunk header describing the layout of a single block of lines + */ public class HunkHeader { /** Details about an old image of the file. */ public abstract static class OldImage { @@ -148,47 +150,83 @@ public class HunkHeader { } } - /** @return header for the file this hunk applies to */ + /** + * Get header for the file this hunk applies to. + * + * @return header for the file this hunk applies to. + */ public FileHeader getFileHeader() { return file; } - /** @return the byte array holding this hunk's patch script. */ + /** + * Get the byte array holding this hunk's patch script. + * + * @return the byte array holding this hunk's patch script. + */ public byte[] getBuffer() { return file.buf; } - /** @return offset the start of this hunk in {@link #getBuffer()}. */ + /** + * Get offset of the start of this hunk in {@link #getBuffer()}. + * + * @return offset of the start of this hunk in {@link #getBuffer()}. + */ public int getStartOffset() { return startOffset; } - /** @return offset one past the end of the hunk in {@link #getBuffer()}. */ + /** + * Get offset one past the end of the hunk in {@link #getBuffer()}. + * + * @return offset one past the end of the hunk in {@link #getBuffer()}. + */ public int getEndOffset() { return endOffset; } - /** @return information about the old image mentioned in this hunk. */ + /** + * Get information about the old image mentioned in this hunk. + * + * @return information about the old image mentioned in this hunk. + */ public OldImage getOldImage() { return old; } - /** @return first line number in the post-image file where the hunk starts */ + /** + * Get first line number in the post-image file where the hunk starts. + * + * @return first line number in the post-image file where the hunk starts. + */ public int getNewStartLine() { return newStartLine; } - /** @return Total number of post-image lines this hunk covers */ + /** + * Get total number of post-image lines this hunk covers. + * + * @return total number of post-image lines this hunk covers. + */ public int getNewLineCount() { return newLineCount; } - /** @return total number of lines of context appearing in this hunk */ + /** + * Get total number of lines of context appearing in this hunk. + * + * @return total number of lines of context appearing in this hunk. + */ public int getLinesContext() { return nContext; } - /** @return a list describing the content edits performed within the hunk. */ + /** + * Convert to a list describing the content edits performed within the hunk. + * + * @return a list describing the content edits performed within the hunk. + */ public EditList toEditList() { if (editList == null) { editList = new EditList(); @@ -404,6 +442,7 @@ public class HunkHeader { offsets[fileIdx] = end < 0 ? s.length() : end + 1; } + /** {@inheritDoc} */ @SuppressWarnings("nls") @Override public String toString() { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java b/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java index 10ac449d12..05fab92e8b 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/patch/Patch.java @@ -58,7 +58,10 @@ import java.util.List; import org.eclipse.jgit.internal.JGitText; import org.eclipse.jgit.util.TemporaryBuffer; -/** A parsed collection of {@link FileHeader}s from a unified diff patch file */ +/** + * A parsed collection of {@link org.eclipse.jgit.patch.FileHeader}s from a + * unified diff patch file + */ public class Patch { static final byte[] DIFF_GIT = encodeASCII("diff --git "); //$NON-NLS-1$ @@ -81,7 +84,9 @@ public class Patch { /** Formatting errors, if any were identified. */ private final List errors; - /** Create an empty patch. */ + /** + * Create an empty patch. + */ public Patch() { files = new ArrayList<>(); errors = new ArrayList<>(0); @@ -100,7 +105,11 @@ public class Patch { files.add(fh); } - /** @return list of files described in the patch, in occurrence order. */ + /** + * Get list of files described in the patch, in occurrence order. + * + * @return list of files described in the patch, in occurrence order. + */ public List getFiles() { return files; } @@ -115,7 +124,11 @@ public class Patch { errors.add(err); } - /** @return collection of formatting errors, if any. */ + /** + * Get collection of formatting errors. + * + * @return collection of formatting errors, if any. + */ public List getErrors() { return errors; } @@ -130,7 +143,7 @@ public class Patch { * @param is * the stream to read the patch data from. The stream is read * until EOF is reached. - * @throws IOException + * @throws java.io.IOException * there was an error reading from the input stream. */ public void parse(final InputStream is) throws IOException { diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java index 98bcd1accf..091bf683ac 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java @@ -149,7 +149,7 @@ public class PlotCommit extends RevCommit { * child index to obtain. Must be in the range 0 through * {@link #getChildCount()}-1. * @return the specified child. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * an invalid child index was specified. */ public final PlotCommit getChild(final int nth) { @@ -186,7 +186,7 @@ public class PlotCommit extends RevCommit { * ref index to obtain. Must be in the range 0 through * {@link #getRefCount()}-1. * @return the specified ref. - * @throws ArrayIndexOutOfBoundsException + * @throws java.lang.ArrayIndexOutOfBoundsException * an invalid ref index was specified. */ public final Ref getRef(final int nth) { @@ -203,6 +203,7 @@ public class PlotCommit extends RevCommit { return (L) lane; } + /** {@inheritDoc} */ @Override public void reset() { forkingOffLanes = NO_LANES; diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java index a8eb86e232..6a0ba66ba1 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommitList.java @@ -57,13 +57,13 @@ import org.eclipse.jgit.revwalk.RevCommitList; import org.eclipse.jgit.revwalk.RevWalk; /** - * An ordered list of {@link PlotCommit} subclasses. + * An ordered list of {@link org.eclipse.jgit.revplot.PlotCommit} subclasses. *

* Commits are allocated into lanes as they enter the list, based upon their * connections between descendant (child) commits and ancestor (parent) commits. *

- * The source of the list must be a {@link PlotWalk} and {@link #fillTo(int)} - * must be used to populate the list. + * The source of the list must be a {@link org.eclipse.jgit.revplot.PlotWalk} + * and {@link #fillTo(int)} must be used to populate the list. * * @param * type of lane used by the application. @@ -82,6 +82,7 @@ public class PlotCommitList extends private final HashMap laneLength = new HashMap<>( 32); + /** {@inheritDoc} */ @Override public void clear() { super.clear(); @@ -91,6 +92,7 @@ public class PlotCommitList extends laneLength.clear(); } + /** {@inheritDoc} */ @Override public void source(final RevWalk w) { if (!(w instanceof PlotWalk)) @@ -122,6 +124,7 @@ public class PlotCommitList extends result.add((L) p); } + /** {@inheritDoc} */ @Override protected void enter(final int index, final PlotCommit currCommit) { setupChildren(currCommit); @@ -395,7 +398,11 @@ public class PlotCommitList extends } /** - * @return a new Lane appropriate for this particular PlotList. + * Create a new {@link PlotLane} appropriate for this particular + * {@link PlotCommitList}. + * + * @return a new {@link PlotLane} appropriate for this particular + * {@link PlotCommitList}. */ @SuppressWarnings("unchecked") protected L createLane() { @@ -407,6 +414,7 @@ public class PlotCommitList extends * is no longer needed. * * @param lane + * a lane */ protected void recycleLane(final L lane) { // Nothing. diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java index be1f07a38c..8ba8d6e4ca 100644 --- a/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java +++ b/org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotWalk.java @@ -70,11 +70,14 @@ import org.eclipse.jgit.revwalk.RevSort; import org.eclipse.jgit.revwalk.RevTag; import org.eclipse.jgit.revwalk.RevWalk; -/** Specialized RevWalk for visualization of a commit graph. */ +/** + * Specialized RevWalk for visualization of a commit graph. + */ public class PlotWalk extends RevWalk { private Map> reverseRefMap; + /** {@inheritDoc} */ @Override public void dispose() { super.dispose(); @@ -98,8 +101,7 @@ public class PlotWalk extends RevWalk { * * @param refs * additional refs - * - * @throws IOException + * @throws java.io.IOException */ public void addAdditionalRefs(Iterable refs) throws IOException { for (Ref ref : refs) { @@ -114,6 +116,7 @@ public class PlotWalk extends RevWalk { } } + /** {@inheritDoc} */ @Override public void sort(final RevSort s, final boolean use) { if (s == RevSort.TOPO && !use) @@ -121,11 +124,13 @@ public class PlotWalk extends RevWalk { super.sort(s, use); } + /** {@inheritDoc} */ @Override protected RevCommit createCommit(final AnyObjectId id) { return new PlotCommit(id); } + /** {@inheritDoc} */ @Override public RevCommit next() throws MissingObjectException, IncorrectObjectTypeException, IOException { -- 2.39.5