Fix javadoc in org.eclipse.jgit patch and revplot package

Change-Id: I6f1aba98bf7034cb51494c546806cf1b72dd1473
Signed-off-by: Matthias Sohn <matthias.sohn@sap.com>

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;
 	}

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<? extends CombinedHunkHeader> getHunks() {
 		return (List<CombinedHunkHeader>) super.getHunks();
 	}
 
-	/** @return number of ancestor revisions mentioned in this diff. */
+	/**
+	 * {@inheritDoc}
+	 * <p>
+	 *
+	 * @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}
+	 * <p>
+	 * @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}
+	 * <p>
+	 *
+	 * @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}
+	 * <p>
 	 * 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 <code>{@link #getParentCount()} + 1</code>
-	 *            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++)

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);

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.
 	 * <p>
-	 * The default character encoding ({@link Constants#CHARSET}) is assumed for
+	 * The default character encoding
-	 * both the old and new files.
+	 * ({@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<? extends HunkHeader> 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)

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();

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() {

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<FormatError> 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<? extends FileHeader> 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<FormatError> 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 {

org.eclipse.jgit/src/org/eclipse/jgit/revplot/PlotCommit.java

@@ -149,7 +149,7 @@ public class PlotCommit<L extends PlotLane> 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<L extends PlotLane> 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<L extends PlotLane> extends RevCommit {
 		return (L) lane;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void reset() {
 		forkingOffLanes = NO_LANES;

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.
  * <p>
  * Commits are allocated into lanes as they enter the list, based upon their
  * connections between descendant (child) commits and ancestor (parent) commits.
  * <p>
- * The source of the list must be a {@link PlotWalk} and {@link #fillTo(int)}
+ * The source of the list must be a {@link org.eclipse.jgit.revplot.PlotWalk}
- * must be used to populate the list.
+ * and {@link #fillTo(int)} must be used to populate the list.
  *
  * @param <L>
  *            type of lane used by the application.
@@ -82,6 +82,7 @@ public class PlotCommitList<L extends PlotLane> extends
 	private final HashMap<PlotLane, Integer> laneLength = new HashMap<>(
 			32);
 
+	/** {@inheritDoc} */
 	@Override
 	public void clear() {
 		super.clear();
@@ -91,6 +92,7 @@ public class PlotCommitList<L extends PlotLane> extends
 		laneLength.clear();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void source(final RevWalk w) {
 		if (!(w instanceof PlotWalk))
@@ -122,6 +124,7 @@ public class PlotCommitList<L extends PlotLane> extends
 			result.add((L) p);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	protected void enter(final int index, final PlotCommit<L> currCommit) {
 		setupChildren(currCommit);
@@ -395,7 +398,11 @@ public class PlotCommitList<L extends PlotLane> 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<L extends PlotLane> extends
 	 * is no longer needed.
 	 *
 	 * @param lane
+	 *            a lane
 	 */
 	protected void recycleLane(final L lane) {
 		// Nothing.

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<AnyObjectId, Set<Ref>> reverseRefMap;
 
+	/** {@inheritDoc} */
 	@Override
 	public void dispose() {
 		super.dispose();
@@ -98,8 +101,7 @@ public class PlotWalk extends RevWalk {
 	 *
 	 * @param refs
 	 *            additional refs
-	 *
+	 * @throws java.io.IOException
-	 * @throws IOException
 	 */
 	public void addAdditionalRefs(Iterable<Ref> 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 {