Fix javadoc in org.eclipse.jgit treewalk package

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

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java

@@ -51,7 +51,6 @@ import java.nio.CharBuffer;
 
 import org.eclipse.jgit.attributes.AttributesHandler;
 import org.eclipse.jgit.attributes.AttributesNode;
-import org.eclipse.jgit.dircache.DirCacheCheckout;
 import org.eclipse.jgit.errors.CorruptObjectException;
 import org.eclipse.jgit.errors.IncorrectObjectTypeException;
 import org.eclipse.jgit.lib.Constants;
@@ -59,7 +58,6 @@ import org.eclipse.jgit.lib.FileMode;
 import org.eclipse.jgit.lib.MutableObjectId;
 import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.ObjectReader;
-import org.eclipse.jgit.treewalk.filter.TreeFilter;
 import org.eclipse.jgit.util.Paths;
 
 /**
@@ -154,7 +152,9 @@ public abstract class AbstractTreeIterator {
 	 */
 	protected int pathLen;
 
-	/** Create a new iterator with no parent. */
+	/**
+	 * Create a new iterator with no parent.
+	 */
 	protected AbstractTreeIterator() {
 		parent = null;
 		path = new byte[DEFAULT_PATH_SIZE];
@@ -341,7 +341,7 @@ public abstract class AbstractTreeIterator {
 	 * @param name
 	 *            file name to find (will not find a directory).
 	 * @return true if the file exists in this tree; false otherwise.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             tree is invalid.
 	 * @since 4.2
 	 */
@@ -355,7 +355,7 @@ public abstract class AbstractTreeIterator {
 	 * @param name
 	 *            file name to find (will not find a directory).
 	 * @return true if the file exists in this tree; false otherwise.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             tree is invalid.
 	 * @since 4.2
 	 */
@@ -425,7 +425,11 @@ public abstract class AbstractTreeIterator {
 				otherIterator.idBuffer(), otherIterator.idOffset());
 	}
 
-	/** @return true if the entry has a valid ObjectId. */
+	/**
+	 * Whether the entry has a valid ObjectId.
+	 *
+	 * @return {@code true} if the entry has a valid ObjectId.
+	 */
 	public abstract boolean hasId();
 
 	/**
@@ -447,17 +451,29 @@ public abstract class AbstractTreeIterator {
 		out.fromRaw(idBuffer(), idOffset());
 	}
 
-	/** @return the file mode of the current entry. */
+	/**
+	 * Get the file mode of the current entry.
+	 *
+	 * @return the file mode of the current entry.
+	 */
 	public FileMode getEntryFileMode() {
 		return FileMode.fromBits(mode);
 	}
 
-	/** @return the file mode of the current entry as bits */
+	/**
+	 * Get the file mode of the current entry as bits.
+	 *
+	 * @return the file mode of the current entry as bits.
+	 */
 	public int getEntryRawMode() {
 		return mode;
 	}
 
-	/** @return path of the current entry, as a string. */
+	/**
+	 * Get path of the current entry, as a string.
+	 *
+	 * @return path of the current entry, as a string.
+	 */
 	public String getEntryPathString() {
 		return TreeWalk.pathOf(this);
 	}
@@ -474,7 +490,11 @@ public abstract class AbstractTreeIterator {
 		return path;
 	}
 
-	/** @return length of the path in {@link #getEntryPathBuffer()}. */
+	/**
+	 * Get length of the path in {@link #getEntryPathBuffer()}.
+	 *
+	 * @return length of the path in {@link #getEntryPathBuffer()}.
+	 */
 	public int getEntryPathLength() {
 		return pathLen;
 	}
@@ -529,10 +549,10 @@ public abstract class AbstractTreeIterator {
 	 * @param reader
 	 *            reader to load the tree data from.
 	 * @return a new parser that walks over the current subtree.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the current entry is not actually a tree and cannot be parsed
 	 *             as though it were a tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public abstract AbstractTreeIterator createSubtreeIterator(
@@ -560,10 +580,10 @@ public abstract class AbstractTreeIterator {
 	 * @param idBuffer
 	 *            temporary ObjectId buffer for use by this method.
 	 * @return a new parser that walks over the current subtree.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the current entry is not actually a tree and cannot be parsed
 	 *             as though it were a tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public AbstractTreeIterator createSubtreeIterator(
@@ -580,7 +600,7 @@ public abstract class AbstractTreeIterator {
 	 * method of repositioning the iterator to its first entry, so subclasses
 	 * are strongly encouraged to override the method.
 	 *
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the tree is invalid.
 	 */
 	public void reset() throws CorruptObjectException {
@@ -629,7 +649,7 @@ public abstract class AbstractTreeIterator {
 	 * @param delta
 	 *            number of entries to move the iterator by. Must be a positive,
 	 *            non-zero integer.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the tree is invalid.
 	 */
 	public abstract void next(int delta) throws CorruptObjectException;
@@ -653,7 +673,7 @@ public abstract class AbstractTreeIterator {
 	 * @param delta
 	 *            number of entries to move the iterator by. Must be a positive,
 	 *            non-zero integer.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the tree is invalid.
 	 */
 	public abstract void back(int delta) throws CorruptObjectException;
@@ -662,11 +682,12 @@ public abstract class AbstractTreeIterator {
 	 * Advance to the next tree entry, populating this iterator with its data.
 	 * <p>
 	 * This method behaves like <code>seek(1)</code> but is called by
-	 * {@link TreeWalk} only if a {@link TreeFilter} was used and ruled out the
+	 * {@link org.eclipse.jgit.treewalk.TreeWalk} only if a
-	 * current entry from the results. In such cases this tree iterator may
+	 * {@link org.eclipse.jgit.treewalk.filter.TreeFilter} was used and ruled
-	 * perform special behavior.
+	 * out the current entry from the results. In such cases this tree iterator
+	 * may perform special behavior.
 	 *
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the tree is invalid.
 	 */
 	public void skip() throws CorruptObjectException {
@@ -685,7 +706,9 @@ public abstract class AbstractTreeIterator {
 	}
 
 	/**
-	 * @return true if the iterator implements {@link #stopWalk()}.
+	 * Whether the iterator implements {@link #stopWalk()}.
+	 *
+	 * @return {@code true} if the iterator implements {@link #stopWalk()}.
 	 * @since 4.2
 	 */
 	protected boolean needsStopWalk() {
@@ -693,14 +716,18 @@ public abstract class AbstractTreeIterator {
 	}
 
 	/**
-	 * @return the length of the name component of the path for the current entry
+	 * Get the length of the name component of the path for the current entry.
+	 *
+	 * @return the length of the name component of the path for the current
+	 *         entry.
 	 */
 	public int getNameLength() {
 		return pathLen - pathOffset;
 	}
 
 	/**
-	 * JGit internal API for use by {@link DirCacheCheckout}
+	 * JGit internal API for use by
+	 * {@link org.eclipse.jgit.dircache.DirCacheCheckout}
 	 *
 	 * @return start of name component part within {@link #getEntryPathBuffer()}
 	 * @since 2.0
@@ -724,6 +751,7 @@ public abstract class AbstractTreeIterator {
 		System.arraycopy(path, pathOffset, buffer, offset, pathLen - pathOffset);
 	}
 
+	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {
@@ -731,8 +759,10 @@ public abstract class AbstractTreeIterator {
 	}
 
 	/**
-	 * @return whether or not this Iterator is iterating through the Work Tree
+	 * Whether or not this Iterator is iterating through the working tree.
 	 *
+	 * @return whether or not this Iterator is iterating through the working
+	 *         tree
 	 * @since 4.3
 	 */
 	public boolean isWorkTree() {

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java

@@ -66,7 +66,9 @@ import org.eclipse.jgit.lib.MutableObjectId;
 import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.ObjectReader;
 
-/** Parses raw Git trees from the canonical semi-text/semi-binary format. */
+/**
+ * Parses raw Git trees from the canonical semi-text/semi-binary format.
+ */
 public class CanonicalTreeParser extends AbstractTreeIterator {
 	private static final byte[] EMPTY = {};
 	private static final byte[] ATTRS = encode(DOT_GIT_ATTRIBUTES);
@@ -82,7 +84,9 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	/** Offset one past the current entry (first byte of next entry). */
 	private int nextPtr;
 
-	/** Create a new parser. */
+	/**
+	 * Create a new parser.
+	 */
 	public CanonicalTreeParser() {
 		reset(EMPTY);
 	}
@@ -102,10 +106,10 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	 *            messages if data corruption is found.
 	 * @throws MissingObjectException
 	 *             the object supplied is not available from the repository.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the object supplied as an argument is not actually a tree and
 	 *             cannot be parsed as though it were a tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public CanonicalTreeParser(final byte[] prefix, final ObjectReader reader,
@@ -120,7 +124,9 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	}
 
 	/**
-	 * @return the parent of this tree parser
+	 * Get the parent of this tree parser.
+	 *
+	 * @return the parent of this tree parser.
 	 * @deprecated internal use only
 	 */
 	@Deprecated
@@ -156,10 +162,10 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	 * @return the root level parser.
 	 * @throws MissingObjectException
 	 *             the object supplied is not available from the repository.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the object supplied as an argument is not actually a tree and
 	 *             cannot be parsed as though it were a tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public CanonicalTreeParser resetRoot(final ObjectReader reader,
@@ -172,7 +178,11 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 		return p;
 	}
 
-	/** @return this iterator, or its parent, if the tree is at eof. */
+	/**
+	 * Get this iterator, or its parent, if the tree is at eof.
+	 *
+	 * @return this iterator, or its parent, if the tree is at eof.
+	 */
 	public CanonicalTreeParser next() {
 		CanonicalTreeParser p = this;
 		for (;;) {
@@ -203,10 +213,10 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	 *            messages if data corruption is found.
 	 * @throws MissingObjectException
 	 *             the object supplied is not available from the repository.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the object supplied as an argument is not actually a tree and
 	 *             cannot be parsed as though it were a tree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public void reset(final ObjectReader reader, final AnyObjectId id)
@@ -214,6 +224,7 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 		reset(reader.open(id, OBJ_TREE).getCachedBytes());
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public CanonicalTreeParser createSubtreeIterator(final ObjectReader reader,
 			final MutableObjectId idBuffer)
@@ -238,7 +249,7 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	 * @param id
 	 *            ObjectId of the tree to open.
 	 * @return a new parser that walks over the current subtree.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public final CanonicalTreeParser createSubtreeIterator0(
@@ -249,43 +260,51 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 		return p;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public CanonicalTreeParser createSubtreeIterator(final ObjectReader reader)
 			throws IncorrectObjectTypeException, IOException {
 		return createSubtreeIterator(reader, new MutableObjectId());
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean hasId() {
 		return true;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public byte[] idBuffer() {
 		return raw;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int idOffset() {
 		return nextPtr - OBJECT_ID_LENGTH;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void reset() {
 		if (!first())
 			reset(raw);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean first() {
 		return currPtr == 0;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean eof() {
 		return currPtr == raw.length;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void next(int delta) {
 		if (delta == 1) {
@@ -315,6 +334,7 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 			parseEntry();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void back(int delta) {
 		if (delta == 1 && 0 <= prevPtr) {
@@ -381,12 +401,15 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	}
 
 	/**
-	 * Retrieve the {@link AttributesNode} for the current entry.
+	 * Retrieve the {@link org.eclipse.jgit.attributes.AttributesNode} for the
+	 * current entry.
 	 *
 	 * @param reader
-	 *            {@link ObjectReader} used to parse the .gitattributes entry.
+	 *            {@link org.eclipse.jgit.lib.ObjectReader} used to parse the
-	 * @return {@link AttributesNode} for the current entry.
+	 *            .gitattributes entry.
-	 * @throws IOException
+	 * @return {@link org.eclipse.jgit.attributes.AttributesNode} for the
+	 *         current entry.
+	 * @throws java.io.IOException
 	 * @since 4.2
 	 */
 	public AttributesNode getEntryAttributesNode(ObjectReader reader)

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java

@@ -52,9 +52,13 @@ import org.eclipse.jgit.errors.IncorrectObjectTypeException;
 import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.ObjectReader;
 
-/** Iterator over an empty tree (a directory with no files). */
+/**
+ * Iterator over an empty tree (a directory with no files).
+ */
 public class EmptyTreeIterator extends AbstractTreeIterator {
-	/** Create a new iterator with no parent. */
+	/**
+	 * Create a new iterator with no parent.
+	 */
 	public EmptyTreeIterator() {
 		// Create a root empty tree.
 	}
@@ -86,63 +90,75 @@ public class EmptyTreeIterator extends AbstractTreeIterator {
 		pathLen = childPathOffset - 1;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader)
 			throws IncorrectObjectTypeException, IOException {
 		return new EmptyTreeIterator(this);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean hasId() {
 		return false;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public ObjectId getEntryObjectId() {
 		return ObjectId.zeroId();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public byte[] idBuffer() {
 		return zeroid;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int idOffset() {
 		return 0;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void reset() {
 		// Do nothing.
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean first() {
 		return true;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean eof() {
 		return true;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void next(final int delta) throws CorruptObjectException {
 		// Do nothing.
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void back(final int delta) throws CorruptObjectException {
 		// Do nothing.
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void stopWalk() {
 		if (parent != null)
 			parent.stopWalk();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	protected boolean needsStopWalk() {
 		return parent != null && parent.needsStopWalk();

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/FileTreeIterator.java

@@ -63,7 +63,8 @@ import org.eclipse.jgit.util.FS;
  * Working directory iterator for standard Java IO.
  * <p>
  * This iterator uses the standard <code>java.io</code> package to read the
- * specified working directory as part of a {@link TreeWalk}.
+ * specified working directory as part of a
+ * {@link org.eclipse.jgit.treewalk.TreeWalk}.
  */
 public class FileTreeIterator extends WorkingTreeIterator {
 	/**
@@ -108,7 +109,6 @@ public class FileTreeIterator extends WorkingTreeIterator {
 	 * @param fileModeStrategy
 	 *            the strategy to use to determine the FileMode for a FileEntry;
 	 *            controls gitlinks etc.
-	 *
 	 * @since 4.3
 	 */
 	public FileTreeIterator(Repository repo, FileModeStrategy fileModeStrategy) {
@@ -148,7 +148,6 @@ public class FileTreeIterator extends WorkingTreeIterator {
 	 * @param fileModeStrategy
 	 *            the strategy to use to determine the FileMode for a FileEntry;
 	 *            controls gitlinks etc.
-	 *
 	 * @since 4.3
 	 */
 	public FileTreeIterator(final File root, FS fs, WorkingTreeOptions options,
@@ -192,7 +191,6 @@ public class FileTreeIterator extends WorkingTreeIterator {
 	 * @param fs
 	 *            the file system abstraction which will be necessary to perform
 	 *            certain file system operations.
-	 *
 	 * @since 4.3
 	 */
 	protected FileTreeIterator(final FileTreeIterator p, final File root,
@@ -215,7 +213,6 @@ public class FileTreeIterator extends WorkingTreeIterator {
 	 * @param fileModeStrategy
 	 *            the strategy to use to determine the FileMode for a given
 	 *            FileEntry.
-	 *
 	 * @since 4.3
 	 */
 	protected FileTreeIterator(final WorkingTreeIterator p, final File root,
@@ -227,6 +224,7 @@ public class FileTreeIterator extends WorkingTreeIterator {
 		init(entries());
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader)
 			throws IncorrectObjectTypeException, IOException {
@@ -407,6 +405,8 @@ public class FileTreeIterator extends WorkingTreeIterator {
 	}
 
 	/**
+	 * <p>Getter for the field <code>directory</code>.</p>
+	 *
 	 * @return The root directory of this iterator
 	 */
 	public File getDirectory() {
@@ -414,6 +414,8 @@ public class FileTreeIterator extends WorkingTreeIterator {
 	}
 
 	/**
+	 * Get the location of the working file.
+	 *
 	 * @return The location of the working file. This is the same as {@code new
 	 *         File(getDirectory(), getEntryPath())} but may be faster by
 	 *         reusing an internal File instance.
@@ -422,11 +424,13 @@ public class FileTreeIterator extends WorkingTreeIterator {
 		return ((FileEntry) current()).getFile();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	protected byte[] idSubmodule(final Entry e) {
 		return idSubmodule(getDirectory(), e);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	protected String readSymlinkTarget(Entry entry) throws IOException {
 		return fs.readSymLink(getEntryFile());

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/NameConflictTreeWalk.java

@@ -46,7 +46,6 @@ package org.eclipse.jgit.treewalk;
 import java.io.IOException;
 
 import org.eclipse.jgit.annotations.Nullable;
-import org.eclipse.jgit.dircache.DirCacheBuilder;
 import org.eclipse.jgit.errors.CorruptObjectException;
 import org.eclipse.jgit.lib.FileMode;
 import org.eclipse.jgit.lib.ObjectReader;
@@ -55,24 +54,26 @@ import org.eclipse.jgit.lib.Repository;
 /**
  * Specialized TreeWalk to detect directory-file (D/F) name conflicts.
  * <p>
- * Due to the way a Git tree is organized the standard {@link TreeWalk} won't
+ * Due to the way a Git tree is organized the standard
- * easily find a D/F conflict when merging two or more trees together. In the
+ * {@link org.eclipse.jgit.treewalk.TreeWalk} won't easily find a D/F conflict
- * standard TreeWalk the file will be returned first, and then much later the
+ * when merging two or more trees together. In the standard TreeWalk the file
- * directory will be returned. This makes it impossible for the application to
+ * will be returned first, and then much later the directory will be returned.
- * efficiently detect and handle the conflict.
+ * This makes it impossible for the application to efficiently detect and handle
+ * the conflict.
  * <p>
  * Using this walk implementation causes the directory to report earlier than
  * usual, at the same time as the non-directory entry. This permits the
  * application to handle the D/F conflict in a single step. The directory is
  * returned only once, so it does not get returned later in the iteration.
  * <p>
- * When a D/F conflict is detected {@link TreeWalk#isSubtree()} will return true
+ * When a D/F conflict is detected
- * and {@link TreeWalk#enterSubtree()} will recurse into the subtree, no matter
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#isSubtree()} will return true and
- * which iterator originally supplied the subtree.
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#enterSubtree()} will recurse into
+ * the subtree, no matter which iterator originally supplied the subtree.
  * <p>
  * Because conflicted directories report early, using this walk implementation
- * to populate a {@link DirCacheBuilder} may cause the automatic resorting to
+ * to populate a {@link org.eclipse.jgit.dircache.DirCacheBuilder} may cause the
- * run and fix the entry ordering.
+ * automatic resorting to run and fix the entry ordering.
  * <p>
  * This walk implementation requires more CPU to implement a look-ahead and a
  * look-behind to merge a D/F pair together, or to skip a previously reported

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/TreeWalk.java

@@ -81,7 +81,8 @@ import org.eclipse.jgit.util.RawParseUtils;
 import org.eclipse.jgit.util.io.EolStreamTypeUtil;
 
 /**
- * Walks one or more {@link AbstractTreeIterator}s in parallel.
+ * Walks one or more {@link org.eclipse.jgit.treewalk.AbstractTreeIterator}s in
+ * parallel.
  * <p>
  * This class can perform n-way differences across as many trees as necessary.
  * <p>
@@ -97,8 +98,9 @@ import org.eclipse.jgit.util.io.EolStreamTypeUtil;
  * usage of a TreeWalk instance to a single thread, or implement their own
  * synchronization at a higher level.
  * <p>
- * Multiple simultaneous TreeWalk instances per {@link Repository} are
+ * Multiple simultaneous TreeWalk instances per
- * permitted, even from concurrent threads.
+ * {@link org.eclipse.jgit.lib.Repository} are permitted, even from concurrent
+ * threads.
  */
 public class TreeWalk implements AutoCloseable, AttributesProvider {
 	private static final AbstractTreeIterator[] NO_TREES = {};
@@ -131,7 +133,11 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	private Map<String, String> filterCommandsByNameDotType = new HashMap<>();
 
 	/**
+	 * Set the operation type of this walk
+	 *
 	 * @param operationType
+	 *            a {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType}
+	 *            object.
 	 * @since 4.2
 	 */
 	public void setOperationType(OperationType operationType) {
@@ -153,14 +159,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 *            one or more trees to walk through, all with the same root.
 	 * @return a new tree walk configured for exactly this one path; null if no
 	 *         path was found in any of the trees.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             reading a pack file or loose object failed.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             an tree object could not be read as its data stream did not
 	 *             appear to be a tree, or could not be inflated.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             an object we expected to be a tree was not a tree.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a tree object was not found.
 	 */
 	public static TreeWalk forPath(final ObjectReader reader, final String path,
@@ -178,7 +184,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 *
 	 * @param repo
 	 *            repository to read config data and
-	 *            {@link AttributesNodeProvider} from.
+	 *            {@link org.eclipse.jgit.attributes.AttributesNodeProvider}
+	 *            from.
 	 * @param reader
 	 *            the reader the walker will obtain tree data from.
 	 * @param path
@@ -187,14 +194,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 *            one or more trees to walk through, all with the same root.
 	 * @return a new tree walk configured for exactly this one path; null if no
 	 *         path was found in any of the trees.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             reading a pack file or loose object failed.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             an tree object could not be read as its data stream did not
 	 *             appear to be a tree, or could not be inflated.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             an object we expected to be a tree was not a tree.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a tree object was not found.
 	 * @since 4.3
 	 */
@@ -234,14 +241,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 *            one or more trees to walk through, all with the same root.
 	 * @return a new tree walk configured for exactly this one path; null if no
 	 *         path was found in any of the trees.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             reading a pack file or loose object failed.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             an tree object could not be read as its data stream did not
 	 *             appear to be a tree, or could not be inflated.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             an object we expected to be a tree was not a tree.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a tree object was not found.
 	 */
 	public static TreeWalk forPath(final Repository db, final String path,
@@ -267,14 +274,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 *            the single tree to walk through.
 	 * @return a new tree walk configured for exactly this one path; null if no
 	 *         path was found in any of the trees.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             reading a pack file or loose object failed.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             an tree object could not be read as its data stream did not
 	 *             appear to be a tree, or could not be inflated.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             an object we expected to be a tree was not a tree.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a tree object was not found.
 	 */
 	public static TreeWalk forPath(final Repository db, final String path,
@@ -373,13 +380,19 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 		this.closeReader = closeReader;
 	}
 
-	/** @return the reader this walker is using to load objects. */
+	/**
+	 * Get the reader this walker is using to load objects.
+	 *
+	 * @return the reader this walker is using to load objects.
+	 */
 	public ObjectReader getObjectReader() {
 		return reader;
 	}
 
 	/**
-	 * @return the {@link OperationType}
+	 * Get the operation type
+	 *
+	 * @return the {@link org.eclipse.jgit.treewalk.TreeWalk.OperationType}
 	 * @since 4.3
 	 */
 	public OperationType getOperationType() {
@@ -387,6 +400,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
+	 * {@inheritDoc}
+	 * <p>
 	 * Release any resources used by this walker's reader.
 	 * <p>
 	 * A walker that has been released can be used again, but may need to be
@@ -421,12 +436,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * Note that filters are not thread-safe and may not be shared by concurrent
 	 * TreeWalk instances. Every TreeWalk must be supplied its own unique
 	 * filter, unless the filter implementation specifically states it is (and
-	 * always will be) thread-safe. Callers may use {@link TreeFilter#clone()}
+	 * always will be) thread-safe. Callers may use
-	 * to create a unique filter tree for this TreeWalk instance.
+	 * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#clone()} to create a
+	 * unique filter tree for this TreeWalk instance.
 	 *
 	 * @param newFilter
-	 *            the new filter. If null the special {@link TreeFilter#ALL}
+	 *            the new filter. If null the special
-	 *            filter will be used instead, as it matches every entry.
+	 *            {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ALL} filter
+	 *            will be used instead, as it matches every entry.
 	 * @see org.eclipse.jgit.treewalk.filter.AndTreeFilter
 	 * @see org.eclipse.jgit.treewalk.filter.OrTreeFilter
 	 */
@@ -493,19 +510,23 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
-	 * Sets the {@link AttributesNodeProvider} for this {@link TreeWalk}.
+	 * Sets the {@link org.eclipse.jgit.attributes.AttributesNodeProvider} for
+	 * this {@link org.eclipse.jgit.treewalk.TreeWalk}.
 	 * <p>
-	 * This is a requirement for a correct computation of the git attributes.
+	 * This is a requirement for a correct computation of the git attributes. If
-	 * If this {@link TreeWalk} has been built using
+	 * this {@link org.eclipse.jgit.treewalk.TreeWalk} has been built using
 	 * {@link #TreeWalk(Repository)} constructor, the
-	 * {@link AttributesNodeProvider} has already been set. Indeed,the
+	 * {@link org.eclipse.jgit.attributes.AttributesNodeProvider} has already
-	 * {@link Repository} can provide an {@link AttributesNodeProvider} using
+	 * been set. Indeed,the {@link org.eclipse.jgit.lib.Repository} can provide
-	 * {@link Repository#createAttributesNodeProvider()} method. Otherwise you
+	 * an {@link org.eclipse.jgit.attributes.AttributesNodeProvider} using
-	 * should provide one.
+	 * {@link org.eclipse.jgit.lib.Repository#createAttributesNodeProvider()}
+	 * method. Otherwise you should provide one.
 	 * </p>
 	 *
 	 * @see Repository#createAttributesNodeProvider()
 	 * @param provider
+	 *            a {@link org.eclipse.jgit.attributes.AttributesNodeProvider}
+	 *            object.
 	 * @since 4.2
 	 */
 	public void setAttributesNodeProvider(AttributesNodeProvider provider) {
@@ -513,7 +534,10 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
-	 * @return the {@link AttributesNodeProvider} for this {@link TreeWalk}.
+	 * Get the attributes node provider
+	 *
+	 * @return the {@link org.eclipse.jgit.attributes.AttributesNodeProvider}
+	 *         for this {@link org.eclipse.jgit.treewalk.TreeWalk}.
 	 * @since 4.3
 	 */
 	public AttributesNodeProvider getAttributesNodeProvider() {
@@ -521,6 +545,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
+	 * {@inheritDoc}
+	 * <p>
 	 * Retrieve the git attributes for the current entry.
 	 *
 	 * <h4>Git attribute computation</h4>
@@ -556,7 +582,6 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * provided it will fallback on the {@link DirCacheIterator}.
 	 * </p>
 	 *
-	 * @return a {@link Set} of {@link Attribute}s that match the current entry.
 	 * @since 4.2
 	 */
 	@Override
@@ -587,11 +612,15 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
+	 * Get the EOL stream type of the current entry using the config and
+	 * {@link #getAttributes()}.
+	 *
 	 * @param opType
 	 *            the operationtype (checkin/checkout) which should be used
 	 * @return the EOL stream type of the current entry using the config and
-	 *         {@link #getAttributes()} Note that this method may return null if
+	 *         {@link #getAttributes()}. Note that this method may return null
-	 *         the {@link TreeWalk} is not based on a working tree
+	 *         if the {@link org.eclipse.jgit.treewalk.TreeWalk} is not based on
+	 *         a working tree
 	 * @since 4.10
 	 */
 	@Nullable
@@ -604,9 +633,13 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
+	 * Get the EOL stream type of the current entry using the config and
+	 * {@link #getAttributes()}.
+	 *
 	 * @return the EOL stream type of the current entry using the config and
-	 *         {@link #getAttributes()} Note that this method may return null if
+	 *         {@link #getAttributes()}. Note that this method may return null
-	 *         the {@link TreeWalk} is not based on a working tree
+	 *         if the {@link org.eclipse.jgit.treewalk.TreeWalk} is not based on
+	 *         a working tree
 	 * @since 4.3
 	 * @deprecated use {@link #getEolStreamType(OperationType)} instead.
 	 */
@@ -615,7 +648,9 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 		return (getEolStreamType(operationType));
 	}
 
-	/** Reset this walker so new tree iterators can be added to it. */
+	/**
+	 * Reset this walker so new tree iterators can be added to it.
+	 */
 	public void reset() {
 		attrs = null;
 		attributesHandler = null;
@@ -630,16 +665,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * @param id
 	 *            the tree we need to parse. The walker will execute over this
 	 *            single tree if the reset is successful.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             the given tree object does not exist in this repository.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the given object id does not denote a tree, but instead names
 	 *             some other non-tree type of object. Note that commits are not
 	 *             trees, even if they are sometimes called a "tree-ish".
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the object claimed to be a tree, but its contents did not
 	 *             appear to be a tree. The repository may have data corruption.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public void reset(final AnyObjectId id) throws MissingObjectException,
@@ -671,16 +706,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * @param ids
 	 *            the trees we need to parse. The walker will execute over this
 	 *            many parallel trees if the reset is successful.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             the given tree object does not exist in this repository.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the given object id does not denote a tree, but instead names
 	 *             some other non-tree type of object. Note that commits are not
 	 *             trees, even if they are sometimes called a "tree-ish".
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the object claimed to be a tree, but its contents did not
 	 *             appear to be a tree. The repository may have data corruption.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public void reset(final AnyObjectId... ids) throws MissingObjectException,
@@ -726,16 +761,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * @param id
 	 *            identity of the tree object the caller wants walked.
 	 * @return position of this tree within the walker.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             the given tree object does not exist in this repository.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             the given object id does not denote a tree, but instead names
 	 *             some other non-tree type of object. Note that commits are not
 	 *             trees, even if they are sometimes called a "tree-ish".
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the object claimed to be a tree, but its contents did not
 	 *             appear to be a tree. The repository may have data corruption.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public int addTree(final AnyObjectId id) throws MissingObjectException,
@@ -786,19 +821,19 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 *
 	 * @return true if there is an entry available; false if all entries have
 	 *         been walked and the walk of this set of tree iterators is over.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             {@link #isRecursive()} was enabled, a subtree was found, but
 	 *             the subtree object does not exist in this repository. The
 	 *             repository may be missing objects.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             {@link #isRecursive()} was enabled, a subtree was found, and
 	 *             the subtree id does not denote a tree, but instead names some
 	 *             other non-tree type of object. The repository may have data
 	 *             corruption.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the contents of a tree did not appear to be a tree. The
 	 *             repository may have data corruption.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public boolean next() throws MissingObjectException,
@@ -873,8 +908,6 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * iterators to manage only one list of items, with the diving handled by
 	 * recursive trees.
 	 *
-	 * @param <T>
-	 *            type of the tree iterator expected by the caller.
 	 * @param nth
 	 *            tree to obtain the current iterator of.
 	 * @param clazz
@@ -890,11 +923,13 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
-	 * Obtain the raw {@link FileMode} bits for the current entry.
+	 * Obtain the raw {@link org.eclipse.jgit.lib.FileMode} bits for the current
+	 * entry.
 	 * <p>
 	 * Every added tree supplies mode bits, even if the tree does not contain
-	 * the current entry. In the latter case {@link FileMode#MISSING}'s mode
+	 * the current entry. In the latter case
-	 * bits (0) are returned.
+	 * {@link org.eclipse.jgit.lib.FileMode#MISSING}'s mode bits (0) are
+	 * returned.
 	 *
 	 * @param nth
 	 *            tree to obtain the mode bits from.
@@ -907,10 +942,11 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
-	 * Obtain the {@link FileMode} for the current entry.
+	 * Obtain the {@link org.eclipse.jgit.lib.FileMode} for the current entry.
 	 * <p>
 	 * Every added tree supplies a mode, even if the tree does not contain the
-	 * current entry. In the latter case {@link FileMode#MISSING} is returned.
+	 * current entry. In the latter case
+	 * {@link org.eclipse.jgit.lib.FileMode#MISSING} is returned.
 	 *
 	 * @param nth
 	 *            tree to obtain the mode from.
@@ -921,7 +957,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
-	 * Obtain the {@link FileMode} for the current entry on the currentHead tree
+	 * Obtain the {@link org.eclipse.jgit.lib.FileMode} for the current entry on
+	 * the currentHead tree
 	 *
 	 * @return mode for the current entry of the currentHead tree.
 	 * @since 4.3
@@ -939,13 +976,16 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * whenever possible.
 	 * <p>
 	 * Every tree supplies an object id, even if the tree does not contain the
-	 * current entry. In the latter case {@link ObjectId#zeroId()} is returned.
+	 * current entry. In the latter case
+	 * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} is returned.
 	 *
 	 * @param nth
 	 *            tree to obtain the object identifier from.
 	 * @return object identifier for the current tree entry.
 	 * @see #getObjectId(MutableObjectId, int)
 	 * @see #idEqual(int, int)
+	 * @see #getObjectId(MutableObjectId, int)
+	 * @see #idEqual(int, int)
 	 */
 	public ObjectId getObjectId(final int nth) {
 		final AbstractTreeIterator t = trees[nth];
@@ -957,7 +997,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * Obtain the ObjectId for the current entry.
 	 * <p>
 	 * Every tree supplies an object id, even if the tree does not contain the
-	 * current entry. In the latter case {@link ObjectId#zeroId()} is supplied.
+	 * current entry. In the latter case
+	 * {@link org.eclipse.jgit.lib.ObjectId#zeroId()} is supplied.
 	 * <p>
 	 * Applications should try to use {@link #idEqual(int, int)} when possible
 	 * as it avoids conversion overheads.
@@ -1055,6 +1096,8 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
+	 * Get the path length of the current entry.
+	 *
 	 * @return The path length of the current entry.
 	 */
 	public int getPathLength() {
@@ -1243,17 +1286,17 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 * If the current entry is a subtree this method arranges for its children
 	 * to be returned before the next sibling following the subtree is returned.
 	 *
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             a subtree was found, but the subtree object does not exist in
 	 *             this repository. The repository may be missing objects.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             a subtree was found, and the subtree id does not denote a
 	 *             tree, but instead names some other non-tree type of object.
 	 *             The repository may have data corruption.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the contents of a tree did not appear to be a tree. The
 	 *             repository may have data corruption.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read.
 	 */
 	public void enterSubtree() throws MissingObjectException,
@@ -1359,10 +1402,14 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	}
 
 	/**
+	 * Get the tree of that type.
+	 *
 	 * @param type
 	 *            of the tree to be queried
-	 * @return the tree of that type or null if none is present
+	 * @return the tree of that type or null if none is present.
 	 * @since 4.3
+	 * @param <T>
+	 *            a tree type.
 	 */
 	public <T extends AbstractTreeIterator> T getTree(
 			Class<T> type) {
@@ -1383,7 +1430,7 @@ public class TreeWalk implements AutoCloseable, AttributesProvider {
 	 *            which type of filterCommand should be executed. E.g. "clean",
 	 *            "smudge"
 	 * @return a filter command
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 * @since 4.2
 	 */
 	public String getFilterCommand(String filterCommandType)

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java

@@ -67,7 +67,6 @@ import org.eclipse.jgit.attributes.AttributesRule;
 import org.eclipse.jgit.attributes.FilterCommand;
 import org.eclipse.jgit.attributes.FilterCommandRegistry;
 import org.eclipse.jgit.diff.RawText;
-import org.eclipse.jgit.dircache.DirCache;
 import org.eclipse.jgit.dircache.DirCacheEntry;
 import org.eclipse.jgit.dircache.DirCacheIterator;
 import org.eclipse.jgit.errors.CorruptObjectException;
@@ -101,13 +100,15 @@ import org.eclipse.jgit.util.io.EolStreamTypeUtil;
 import org.eclipse.jgit.util.sha1.SHA1;
 
 /**
- * Walks a working directory tree as part of a {@link TreeWalk}.
+ * Walks a working directory tree as part of a
+ * {@link org.eclipse.jgit.treewalk.TreeWalk}.
  * <p>
  * Most applications will want to use the standard implementation of this
- * iterator, {@link FileTreeIterator}, as that does all IO through the standard
+ * iterator, {@link org.eclipse.jgit.treewalk.FileTreeIterator}, as that does
- * <code>java.io</code> package. Plugins for a Java based IDE may however wish
+ * all IO through the standard <code>java.io</code> package. Plugins for a Java
- * to create their own implementations of this class to allow traversal of the
+ * based IDE may however wish to create their own implementations of this class
- * IDE's project space, as well as benefit from any caching the IDE may have.
+ * to allow traversal of the IDE's project space, as well as benefit from any
+ * caching the IDE may have.
  *
  * @see FileTreeIterator
  */
@@ -234,7 +235,8 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	}
 
 	/**
-	 * Define the matching {@link DirCacheIterator}, to optimize ObjectIds.
+	 * Define the matching {@link org.eclipse.jgit.dircache.DirCacheIterator},
+	 * to optimize ObjectIds.
 	 *
 	 * Once the DirCacheIterator has been set this iterator must only be
 	 * advanced by the TreeWalk that is supplied, as it assumes that itself and
@@ -244,13 +246,15 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * @param walk
 	 *            the walk that will be advancing this iterator.
 	 * @param treeId
-	 *            index of the matching {@link DirCacheIterator}.
+	 *            index of the matching
+	 *            {@link org.eclipse.jgit.dircache.DirCacheIterator}.
 	 */
 	public void setDirCacheIterator(TreeWalk walk, int treeId) {
 		state.walk = walk;
 		state.dirCacheTree = treeId;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean hasId() {
 		if (contentIdFromPtr == ptr)
@@ -258,6 +262,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 		return (mode & FileMode.TYPE_MASK) == FileMode.TYPE_FILE;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public byte[] idBuffer() {
 		if (contentIdFromPtr == ptr)
@@ -295,6 +300,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 		return zeroid;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean isWorkTree() {
 		return true;
@@ -304,6 +310,8 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * Get submodule id for given entry.
 	 *
 	 * @param e
+	 *            a {@link org.eclipse.jgit.treewalk.WorkingTreeIterator.Entry}
+	 *            object.
 	 * @return non-null submodule id
 	 */
 	protected byte[] idSubmodule(Entry e) {
@@ -323,7 +331,10 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * relative to the directory.
 	 *
 	 * @param directory
+	 *            a {@link java.io.File} object.
 	 * @param e
+	 *            a {@link org.eclipse.jgit.treewalk.WorkingTreeIterator.Entry}
+	 *            object.
 	 * @return non-null submodule id
 	 */
 	protected byte[] idSubmodule(File directory, Entry e) {
@@ -504,11 +515,13 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 		return state.options;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int idOffset() {
 		return contentIdOffset;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void reset() {
 		if (!first()) {
@@ -518,16 +531,19 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean first() {
 		return ptr == 0;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean eof() {
 		return ptr == entryCnt;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void next(final int delta) throws CorruptObjectException {
 		ptr += delta;
@@ -536,6 +552,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void back(final int delta) throws CorruptObjectException {
 		ptr -= delta;
@@ -568,7 +585,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * Get the filtered input length of this entry
 	 *
 	 * @return size of the content, in bytes
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public long getEntryContentLength() throws IOException {
 		if (canonLen == -1) {
@@ -610,7 +627,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * The caller will close the stream once complete.
 	 *
 	 * @return a stream to read from the file.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the file could not be opened for reading.
 	 */
 	public InputStream openEntryStream() throws IOException {
@@ -626,7 +643,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * Determine if the current entry path is ignored by an ignore rule.
 	 *
 	 * @return true if the entry was ignored by an ignore rule file.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a relevant ignore rule file exists but cannot be read.
 	 */
 	public boolean isEntryIgnored() throws IOException {
@@ -639,7 +656,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * @param pLen
 	 *            the length of the path in the path buffer.
 	 * @return true if the entry is ignored by an ignore rule.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a relevant ignore rule file exists but cannot be read.
 	 */
 	protected boolean isEntryIgnored(final int pLen) throws IOException {
@@ -700,12 +717,12 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	}
 
 	/**
-	 * Retrieves the {@link AttributesNode} for the current entry.
+	 * Retrieves the {@link org.eclipse.jgit.attributes.AttributesNode} for the
+	 * current entry.
 	 *
-	 * @return {@link AttributesNode} for the current entry.
+	 * @return the {@link org.eclipse.jgit.attributes.AttributesNode} for the
+	 *         current entry.
 	 * @throws IOException
-	 *             if an error is raised while parsing the .gitattributes file
-	 * @since 3.7
 	 */
 	public AttributesNode getEntryAttributesNode() throws IOException {
 		if (attributesNode instanceof PerDirectoryAttributesNode)
@@ -809,6 +826,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * Is the file mode of the current entry different than the given raw mode?
 	 *
 	 * @param rawMode
+	 *            an int.
 	 * @return true if different, false otherwise
 	 */
 	public boolean isModeDifferent(final int rawMode) {
@@ -835,12 +853,14 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 
 	/**
 	 * Compare the metadata (mode, length, modification-timestamp) of the
-	 * current entry and a {@link DirCacheEntry}
+	 * current entry and a {@link org.eclipse.jgit.dircache.DirCacheEntry}
 	 *
 	 * @param entry
-	 *            the {@link DirCacheEntry} to compare with
+	 *            the {@link org.eclipse.jgit.dircache.DirCacheEntry} to compare
-	 * @return a {@link MetadataDiff} which tells whether and how the entries
+	 *            with
-	 *         metadata differ
+	 * @return a
+	 *         {@link org.eclipse.jgit.treewalk.WorkingTreeIterator.MetadataDiff}
+	 *         which tells whether and how the entries metadata differ
 	 */
 	public MetadataDiff compareMetadata(DirCacheEntry entry) {
 		if (entry.isAssumeValid())
@@ -890,7 +910,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 
 	/**
 	 * Checks whether this entry differs from a given entry from the
-	 * {@link DirCache}.
+	 * {@link org.eclipse.jgit.dircache.DirCache}.
 	 *
 	 * File status information is used and if status is same we consider the
 	 * file identical to the state in the working directory. Native git uses
@@ -904,7 +924,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * @param reader
 	 *            access to repository objects if necessary. Should not be null.
 	 * @return true if content is most likely different.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 * @since 3.3
 	 */
 	public boolean isModified(DirCacheEntry entry, boolean forceContentCheck,
@@ -945,9 +965,10 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * in the index.
 	 *
 	 * @param indexIter
-	 *            {@link DirCacheIterator} positioned at the same entry as this
+	 *            {@link org.eclipse.jgit.dircache.DirCacheIterator} positioned
-	 *            iterator or null if no {@link DirCacheIterator} is available
+	 *            at the same entry as this iterator or null if no
-	 *            at this iterator's current entry
+	 *            {@link org.eclipse.jgit.dircache.DirCacheIterator} is
+	 *            available at this iterator's current entry
 	 * @return index file mode
 	 */
 	public FileMode getIndexFileMode(final DirCacheIterator indexIter) {
@@ -1067,7 +1088,7 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	 * @param entry
 	 *            to read
 	 * @return the entry's content as a normalized string
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             if the entry cannot be read or does not denote a symlink
 	 * @since 4.6
 	 */
@@ -1351,9 +1372,11 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	}
 
 	/**
+	 * Get the clean filter command for the current entry.
+	 *
 	 * @return the clean filter command for the current entry or
 	 *         <code>null</code> if no such command is defined
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 * @since 4.2
 	 */
 	public String getCleanFilterCommand() throws IOException {
@@ -1369,11 +1392,13 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	}
 
 	/**
+	 * Get the eol stream type for the current entry.
+	 *
 	 * @return the eol stream type for the current entry or <code>null</code> if
 	 *         it cannot be determined. When state or state.walk is null or the
-	 *         {@link TreeWalk} is not based on a {@link Repository} then null
+	 *         {@link org.eclipse.jgit.treewalk.TreeWalk} is not based on a
-	 *         is returned.
+	 *         {@link org.eclipse.jgit.lib.Repository} then null is returned.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 * @since 4.3
 	 */
 	public EolStreamType getEolStreamType() throws IOException {

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeOptions.java

@@ -52,7 +52,9 @@ import org.eclipse.jgit.lib.CoreConfig.EOL;
 import org.eclipse.jgit.lib.CoreConfig.HideDotFiles;
 import org.eclipse.jgit.lib.CoreConfig.SymLinks;
 
-/** Options used by the {@link WorkingTreeIterator}. */
+/**
+ * Options used by the {@link org.eclipse.jgit.treewalk.WorkingTreeIterator}.
+ */
 public class WorkingTreeOptions {
 	/** Key for {@link Config#get(SectionParser)}. */
 	public static final Config.SectionParser<WorkingTreeOptions> KEY =
@@ -92,18 +94,29 @@ public class WorkingTreeOptions {
 	}
 
 	/** @return true if the execute bit on working files should be trusted. */
+	/**
+	 * Whether the execute bit on working files should be trusted.
+	 *
+	 * @return {@code true} if the execute bit on working files should be
+	 *         trusted.
+	 */
 	public boolean isFileMode() {
 		return fileMode;
 	}
 
-	/** @return how automatic CRLF conversion has been configured. */
+	/**
+	 * Get automatic CRLF conversion configuration.
+	 *
+	 * @return how automatic CRLF conversion has been configured.
+	 */
 	public AutoCRLF getAutoCRLF() {
 		return autoCRLF;
 	}
 
 	/**
-	 * @return how text line endings should be normalized.
+	 * Get how text line endings should be normalized.
 	 *
+	 * @return how text line endings should be normalized.
 	 * @since 4.3
 	 */
 	public EOL getEOL() {
@@ -111,7 +124,9 @@ public class WorkingTreeOptions {
 	}
 
 	/**
-	 * @return how stat data is compared
+	 * Get how stat data is compared.
+	 *
+	 * @return how stat data is compared.
 	 * @since 3.0
 	 */
 	public CheckStat getCheckStat() {
@@ -119,6 +134,8 @@ public class WorkingTreeOptions {
 	}
 
 	/**
+	 * Get how we handle symbolic links
+	 *
 	 * @return how we handle symbolic links
 	 * @since 3.3
 	 */
@@ -127,6 +144,8 @@ public class WorkingTreeOptions {
 	}
 
 	/**
+	 * Get how we create '.'-files (on Windows)
+	 *
 	 * @return how we create '.'-files (on Windows)
 	 * @since 3.5
 	 */
@@ -135,9 +154,10 @@ public class WorkingTreeOptions {
 	}
 
 	/**
-	 * @return whether or not we treat nested repos as directories.
+	 * Whether or not we treat nested repos as directories.
-	 * 		   If true, folders containing .git entries will not be
+	 *
-	 * 		   treated as gitlinks.
+	 * @return whether or not we treat nested repos as directories. If true,
+	 *         folders containing .git entries will not be treated as gitlinks.
 	 * @since 4.3
 	 */
 	public boolean isDirNoGitLinks() { return dirNoGitLinks; }

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/AndTreeFilter.java

@@ -56,9 +56,10 @@ import org.eclipse.jgit.treewalk.TreeWalk;
  * Includes a tree entry only if all subfilters include the same tree entry.
  * <p>
  * Classic shortcut behavior is used, so evaluation of the
- * {@link TreeFilter#include(TreeWalk)} method stops as soon as a false result
+ * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)} method
- * is obtained. Applications can improve filtering performance by placing faster
+ * stops as soon as a false result is obtained. Applications can improve
- * filters that are more likely to reject a result earlier in the list.
+ * filtering performance by placing faster filters that are more likely to
+ * reject a result earlier in the list.
  */
 public abstract class AndTreeFilter extends TreeFilter {
 	/**

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/ByteArraySet.java

@@ -213,6 +213,7 @@ class ByteArraySet {
 		table = new byte[sz][];
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		StringBuilder sb = new StringBuilder();

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/IndexDiffFilter.java

@@ -58,26 +58,33 @@ import org.eclipse.jgit.treewalk.TreeWalk;
 import org.eclipse.jgit.treewalk.WorkingTreeIterator;
 
 /**
- * A performance optimized variant of {@link TreeFilter#ANY_DIFF} which should
+ * A performance optimized variant of
- * be used when among the walked trees there is a {@link DirCacheIterator} and a
+ * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} which should be
- * {@link WorkingTreeIterator}. Please see the documentation of
+ * used when among the walked trees there is a
- * {@link TreeFilter#ANY_DIFF} for a basic description of the semantics.
+ * {@link org.eclipse.jgit.dircache.DirCacheIterator} and a
+ * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator}. Please see the
+ * documentation of {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF}
+ * for a basic description of the semantics.
  * <p>
  * This filter tries to avoid computing content ids of the files in the
- * working-tree. In contrast to {@link TreeFilter#ANY_DIFF} this filter takes
+ * working-tree. In contrast to
- * care to first compare the entry from the {@link DirCacheIterator} with the
+ * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF} this filter
- * entries from all other iterators besides the {@link WorkingTreeIterator}.
+ * takes care to first compare the entry from the
- * Since all those entries have fast access to content ids that is very fast. If
+ * {@link org.eclipse.jgit.dircache.DirCacheIterator} with the entries from all
- * a difference is detected in this step this filter decides to include that
+ * other iterators besides the
- * path before even looking at the working-tree entry.
+ * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator}. Since all those
+ * entries have fast access to content ids that is very fast. If a difference is
+ * detected in this step this filter decides to include that path before even
+ * looking at the working-tree entry.
  * <p>
  * If no difference is found then we have to compare index and working-tree as
  * the last step. By making use of
- * {@link WorkingTreeIterator#isModified(org.eclipse.jgit.dircache.DirCacheEntry, boolean, ObjectReader)}
+ * {@link org.eclipse.jgit.treewalk.WorkingTreeIterator#isModified(org.eclipse.jgit.dircache.DirCacheEntry, boolean, ObjectReader)}
  * we can avoid the computation of the content id if the file is not dirty.
  * <p>
- * Instances of this filter should not be used for multiple {@link TreeWalk}s.
+ * Instances of this filter should not be used for multiple
- * Always construct a new instance of this filter for each TreeWalk.
+ * {@link org.eclipse.jgit.treewalk.TreeWalk}s. Always construct a new instance
+ * of this filter for each TreeWalk.
  */
 public class IndexDiffFilter extends TreeFilter {
 	private final int dirCache;
@@ -97,11 +104,13 @@ public class IndexDiffFilter extends TreeFilter {
 	 * filter in multiple treewalks.
 	 *
 	 * @param dirCacheIndex
-	 *            the index of the {@link DirCacheIterator} in the associated
+	 *            the index of the
-	 *            treewalk
+	 *            {@link org.eclipse.jgit.dircache.DirCacheIterator} in the
+	 *            associated treewalk
 	 * @param workingTreeIndex
-	 *            the index of the {@link WorkingTreeIterator} in the associated
+	 *            the index of the
-	 *            treewalk
+	 *            {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} in the
+	 *            associated treewalk
 	 */
 	public IndexDiffFilter(int dirCacheIndex, int workingTreeIndex) {
 		this(dirCacheIndex, workingTreeIndex, true /* honor ignores */);
@@ -112,14 +121,16 @@ public class IndexDiffFilter extends TreeFilter {
 	 * filter in multiple treewalks.
 	 *
 	 * @param dirCacheIndex
-	 *            the index of the {@link DirCacheIterator} in the associated
+	 *            the index of the
-	 *            treewalk
+	 *            {@link org.eclipse.jgit.dircache.DirCacheIterator} in the
+	 *            associated treewalk
 	 * @param workingTreeIndex
-	 *            the index of the {@link WorkingTreeIterator} in the associated
+	 *            the index of the
-	 *            treewalk
+	 *            {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} in the
+	 *            associated treewalk
 	 * @param honorIgnores
 	 *            true if the filter should skip working tree files that are
-	 *            declared as ignored by the standard exclude mechanisms..
+	 *            declared as ignored by the standard exclude mechanisms.
 	 */
 	public IndexDiffFilter(int dirCacheIndex, int workingTreeIndex,
 			boolean honorIgnores) {
@@ -128,6 +139,7 @@ public class IndexDiffFilter extends TreeFilter {
 		this.honorIgnores = honorIgnores;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean include(TreeWalk tw) throws MissingObjectException,
 			IncorrectObjectTypeException, IOException {
@@ -255,6 +267,7 @@ public class IndexDiffFilter extends TreeFilter {
 		return tw.getTree(workingTree, WorkingTreeIterator.class);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		// We cannot compare subtrees in the working tree, so encourage
@@ -262,11 +275,13 @@ public class IndexDiffFilter extends TreeFilter {
 		return true;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public TreeFilter clone() {
 		return this;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		return "INDEX_DIFF_FILTER"; //$NON-NLS-1$
@@ -286,9 +301,11 @@ public class IndexDiffFilter extends TreeFilter {
 	}
 
 	/**
+	 * <p>Getter for the field <code>untrackedFolders</code>.</p>
+	 *
 	 * @return all paths of folders which contain only untracked files/folders.
 	 *         If on the associated treewalk postorder traversal was turned on
-	 *         (see {@link TreeWalk#setPostOrderTraversal(boolean)}) then an
+	 *         (see {@link org.eclipse.jgit.treewalk.TreeWalk#setPostOrderTraversal(boolean)}) then an
 	 *         empty list will be returned.
 	 */
 	public List<String> getUntrackedFolders() {

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/InterIndexDiffFilter.java

@@ -49,8 +49,9 @@ import org.eclipse.jgit.treewalk.TreeWalk;
 
 /**
  * A filter for extracting changes between two versions of the dircache. In
- * addition to what {@link TreeFilter#ANY_DIFF} would do, it also detects
+ * addition to what {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF}
- * changes that will affect decorations and show up in an attempt to commit.
+ * would do, it also detects changes that will affect decorations and show up in
+ * an attempt to commit.
  */
 public final class InterIndexDiffFilter extends TreeFilter {
 	private static final int baseTree = 0;
@@ -60,6 +61,7 @@ public final class InterIndexDiffFilter extends TreeFilter {
 	 */
 	public static final TreeFilter INSTANCE = new InterIndexDiffFilter();
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean include(final TreeWalk walker) {
 		final int n = walker.getTreeCount();
@@ -88,16 +90,19 @@ public final class InterIndexDiffFilter extends TreeFilter {
 		return false;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		return false;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public TreeFilter clone() {
 		return this;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		return "INTERINDEX_DIFF"; //$NON-NLS-1$

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotIgnoredFilter.java

@@ -50,7 +50,8 @@ import org.eclipse.jgit.treewalk.TreeWalk;
 import org.eclipse.jgit.treewalk.WorkingTreeIterator;
 
 /**
- * Skip {@link WorkingTreeIterator} entries that appear in gitignore files.
+ * Skip {@link org.eclipse.jgit.treewalk.WorkingTreeIterator} entries that
+ * appear in gitignore files.
  */
 public class NotIgnoredFilter extends TreeFilter {
 	private final int index;
@@ -65,6 +66,7 @@ public class NotIgnoredFilter extends TreeFilter {
 		this.index = workdirTreeIndex;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean include(TreeWalk tw) throws MissingObjectException,
 			IncorrectObjectTypeException, IOException {
@@ -72,17 +74,20 @@ public class NotIgnoredFilter extends TreeFilter {
 		return i == null || !i.isEntryIgnored();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		return false;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public TreeFilter clone() {
 		// immutable
 		return this;
 	}
 
+	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/NotTreeFilter.java

@@ -50,7 +50,9 @@ import org.eclipse.jgit.errors.IncorrectObjectTypeException;
 import org.eclipse.jgit.errors.MissingObjectException;
 import org.eclipse.jgit.treewalk.TreeWalk;
 
-/** Includes an entry only if the subfilter does not include the entry. */
+/**
+ * Includes an entry only if the subfilter does not include the entry.
+ */
 public class NotTreeFilter extends TreeFilter {
 	/**
 	 * Create a filter that negates the result of another filter.
@@ -69,11 +71,13 @@ public class NotTreeFilter extends TreeFilter {
 		a = one;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public TreeFilter negate() {
 		return a;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean include(final TreeWalk walker)
 			throws MissingObjectException, IncorrectObjectTypeException,
@@ -81,6 +85,7 @@ public class NotTreeFilter extends TreeFilter {
 		return matchFilter(walker) == 0;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int matchFilter(TreeWalk walker)
 			throws MissingObjectException, IncorrectObjectTypeException,
@@ -97,17 +102,20 @@ public class NotTreeFilter extends TreeFilter {
 		return -1;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		return a.shouldBeRecursive();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public TreeFilter clone() {
 		final TreeFilter n = a.clone();
 		return n == a ? this : new NotTreeFilter(n);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		return "NOT " + a.toString(); //$NON-NLS-1$

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/OrTreeFilter.java

@@ -56,9 +56,10 @@ import org.eclipse.jgit.treewalk.TreeWalk;
  * Includes a tree entry if any subfilters include the same tree entry.
  * <p>
  * Classic shortcut behavior is used, so evaluation of the
- * {@link TreeFilter#include(TreeWalk)} method stops as soon as a true result is
+ * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)} method
- * obtained. Applications can improve filtering performance by placing faster
+ * stops as soon as a true result is obtained. Applications can improve
- * filters that are more likely to accept a result earlier in the list.
+ * filtering performance by placing faster filters that are more likely to
+ * accept a result earlier in the list.
  */
 public abstract class OrTreeFilter extends TreeFilter {
 	/**

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilter.java

@@ -51,9 +51,10 @@ import org.eclipse.jgit.treewalk.TreeWalk;
 /**
  * Includes tree entries only if they match the configured path.
  * <p>
- * Applications should use {@link PathFilterGroup} to connect these into a tree
+ * Applications should use
- * filter graph, as the group supports breaking out of traversal once it is
+ * {@link org.eclipse.jgit.treewalk.filter.PathFilterGroup} to connect these
- * known the path can never match.
+ * into a tree filter graph, as the group supports breaking out of traversal
+ * once it is known the path can never match.
  */
 public class PathFilter extends TreeFilter {
 	/**
@@ -70,7 +71,7 @@ public class PathFilter extends TreeFilter {
 	 *            trailing '/' characters will be trimmed before string's length
 	 *            is checked or is used as part of the constructed filter.
 	 * @return a new filter for the requested path.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             the path supplied was the empty string.
 	 */
 	public static PathFilter create(String path) {
@@ -90,21 +91,28 @@ public class PathFilter extends TreeFilter {
 		pathRaw = Constants.encode(pathStr);
 	}
 
-	/** @return the path this filter matches. */
+	/**
+	 * Get the path this filter matches.
+	 *
+	 * @return the path this filter matches.
+	 */
 	public String getPath() {
 		return pathStr;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean include(final TreeWalk walker) {
 		return matchFilter(walker) <= 0;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int matchFilter(final TreeWalk walker) {
 		return walker.isPathMatch(pathRaw, pathRaw.length);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		for (final byte b : pathRaw)
@@ -113,11 +121,13 @@ public class PathFilter extends TreeFilter {
 		return false;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public PathFilter clone() {
 		return this;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	@SuppressWarnings("nls")
 	public String toString() {
@@ -125,6 +135,9 @@ public class PathFilter extends TreeFilter {
 	}
 
 	/**
+	 * Whether the path length of this filter matches the length of the current
+	 * path of the supplied TreeWalk.
+	 *
 	 * @param walker
 	 *            The walk to check against.
 	 * @return {@code true} if the path length of this filter matches the length

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathFilterGroup.java

@@ -55,10 +55,11 @@ import org.eclipse.jgit.util.RawParseUtils;
 /**
  * Includes tree entries only if they match one or more configured paths.
  * <p>
- * Operates like {@link PathFilter} but causes the walk to abort as soon as the
+ * Operates like {@link org.eclipse.jgit.treewalk.filter.PathFilter} but causes
- * tree can no longer match any of the paths within the group. This may bypass
+ * the walk to abort as soon as the tree can no longer match any of the paths
- * the boolean logic of a higher level AND or OR group, but does improve
+ * within the group. This may bypass the boolean logic of a higher level AND or
- * performance for the common case of examining one or more modified paths.
+ * OR group, but does improve performance for the common case of examining one
+ * or more modified paths.
  * <p>
  * This filter is effectively an OR group around paths, with the early abort
  * feature described above.

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/PathSuffixFilter.java

@@ -59,8 +59,8 @@ import org.eclipse.jgit.treewalk.TreeWalk;
  * paths ending in <code>.txt</code>.
  * <p>
  * Using this filter is recommended instead of filtering the entries using
- * {@link TreeWalk#getPathString()} and <code>endsWith</code> or some other type
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#getPathString()} and
- * of string match function.
+ * <code>endsWith</code> or some other type of string match function.
  */
 public class PathSuffixFilter extends TreeFilter {
 
@@ -72,7 +72,7 @@ public class PathSuffixFilter extends TreeFilter {
 	 * @param path
 	 *            the path suffix to filter on. Must not be the empty string.
 	 * @return a new filter for the requested path.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             the path supplied was the empty string.
 	 */
 	public static PathSuffixFilter create(String path) {
@@ -89,11 +89,13 @@ public class PathSuffixFilter extends TreeFilter {
 		pathRaw = Constants.encode(pathStr);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public TreeFilter clone() {
 		return this;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean include(TreeWalk walker) throws MissingObjectException,
 			IncorrectObjectTypeException, IOException {
@@ -104,6 +106,7 @@ public class PathSuffixFilter extends TreeFilter {
 
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		return true;

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/SkipWorkTreeFilter.java

@@ -69,6 +69,7 @@ public class SkipWorkTreeFilter extends TreeFilter {
 		this.treeIdx = treeIdx;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean include(TreeWalk walker) {
 		DirCacheIterator i = walker.getTree(treeIdx, DirCacheIterator.class);
@@ -79,16 +80,19 @@ public class SkipWorkTreeFilter extends TreeFilter {
 		return e == null || !e.isSkipWorkTree();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		return false;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public TreeFilter clone() {
 		return this;
 	}
 
+	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilter.java

@@ -67,7 +67,8 @@ import org.eclipse.jgit.treewalk.WorkingTreeIterator;
  * <p>
  * <b>Path filters:</b>
  * <ul>
- * <li>Matching pathname: {@link PathFilter}</li>
+ * <li>Matching pathname:
+ * {@link org.eclipse.jgit.treewalk.filter.PathFilter}</li>
  * </ul>
  *
  * <p>
@@ -79,9 +80,9 @@ import org.eclipse.jgit.treewalk.WorkingTreeIterator;
  * <p>
  * <b>Boolean modifiers:</b>
  * <ul>
- * <li>AND: {@link AndTreeFilter}</li>
+ * <li>AND: {@link org.eclipse.jgit.treewalk.filter.AndTreeFilter}</li>
- * <li>OR: {@link OrTreeFilter}</li>
+ * <li>OR: {@link org.eclipse.jgit.treewalk.filter.OrTreeFilter}</li>
- * <li>NOT: {@link NotTreeFilter}</li>
+ * <li>NOT: {@link org.eclipse.jgit.treewalk.filter.NotTreeFilter}</li>
  * </ul>
  */
 public abstract class TreeFilter {
@@ -173,24 +174,25 @@ public abstract class TreeFilter {
 	 * Determine if the current entry is interesting to report.
 	 * <p>
 	 * This method is consulted for subtree entries even if
-	 * {@link TreeWalk#isRecursive()} is enabled. The consultation allows the
+	 * {@link org.eclipse.jgit.treewalk.TreeWalk#isRecursive()} is enabled. The
-	 * filter to bypass subtree recursion on a case-by-case basis, even when
+	 * consultation allows the filter to bypass subtree recursion on a
-	 * recursion is enabled at the application level.
+	 * case-by-case basis, even when recursion is enabled at the application
+	 * level.
 	 *
 	 * @param walker
 	 *            the walker the filter needs to examine.
 	 * @return true if the current entry should be seen by the application;
 	 *         false to hide the entry.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             an object the filter needs to consult to determine its answer
 	 *             does not exist in the Git repository the walker is operating
 	 *             on. Filtering this current walker entry is impossible without
 	 *             the object.
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             an object the filter needed to consult was not of the
 	 *             expected object type. This usually indicates a corrupt
 	 *             repository, as an object link is referencing the wrong type.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a loose object or pack file could not be read to obtain data
 	 *             necessary for the filter to make its decision.
 	 */
@@ -203,19 +205,19 @@ public abstract class TreeFilter {
 	 * <p>
 	 * This method extends the result returned by {@link #include(TreeWalk)}
 	 * with a third option (-1), splitting the value true. This gives the
-	 * application a possibility to distinguish between an exact match
+	 * application a possibility to distinguish between an exact match and the
-	 * and the case when a subtree to the current entry might be a match.
+	 * case when a subtree to the current entry might be a match.
 	 *
 	 * @param walker
 	 *            the walker the filter needs to examine.
-	 * @return -1 if the current entry is a parent of the filter but no
+	 * @return -1 if the current entry is a parent of the filter but no exact
-	 *         exact match has been made; 0 if the current entry should
+	 *         match has been made; 0 if the current entry should be seen by the
-	 *         be seen by the application; 1 if it should be hidden.
+	 *         application; 1 if it should be hidden.
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
 	 *             as thrown by {@link #include(TreeWalk)}
-	 * @throws IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
 	 *             as thrown by {@link #include(TreeWalk)}
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             as thrown by {@link #include(TreeWalk)}
 	 * @since 4.7
 	 */
@@ -241,16 +243,17 @@ public abstract class TreeFilter {
 	public abstract boolean shouldBeRecursive();
 
 	/**
+	 * {@inheritDoc}
+	 *
 	 * Clone this tree filter, including its parameters.
 	 * <p>
 	 * This is a deep clone. If this filter embeds objects or other filters it
 	 * must also clone those, to ensure the instances do not share mutable data.
-	 *
-	 * @return another copy of this filter, suitable for another thread.
 	 */
 	@Override
 	public abstract TreeFilter clone();
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		String n = getClass().getName();

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/filter/TreeFilterMarker.java

@@ -53,8 +53,9 @@ import org.eclipse.jgit.internal.JGitText;
 import org.eclipse.jgit.treewalk.TreeWalk;
 
 /**
- * For testing an array of {@link TreeFilter} during a {@link TreeWalk} for each
+ * For testing an array of {@link org.eclipse.jgit.treewalk.filter.TreeFilter}
- * entry and returning the result as a bitmask.
+ * during a {@link org.eclipse.jgit.treewalk.TreeWalk} for each entry and
+ * returning the result as a bitmask.
  *
  * @since 2.3
  */
@@ -68,8 +69,8 @@ public class TreeFilterMarker {
 	 *
 	 * @param markTreeFilters
 	 *            the filters to use for marking, must not have more elements
-	 *            than {@link Integer#SIZE}.
+	 *            than {@link java.lang.Integer#SIZE}.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             if more tree filters are passed than possible
 	 */
 	public TreeFilterMarker(TreeFilter[] markTreeFilters) {
@@ -85,19 +86,23 @@ public class TreeFilterMarker {
 
 	/**
 	 * Test the filters against the walk. Returns a bitmask where each bit
-	 * represents the result of a call to {@link TreeFilter#include(TreeWalk)},
+	 * represents the result of a call to
+	 * {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)},
 	 * ordered by the index for which the tree filters were passed in the
 	 * constructor.
 	 *
 	 * @param walk
 	 *            the walk from which to test the current entry
 	 * @return the marks bitmask
-	 * @throws MissingObjectException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
-	 *             as thrown by {@link TreeFilter#include(TreeWalk)}
+	 *             as thrown by
-	 * @throws IncorrectObjectTypeException
+	 *             {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)}
-	 *             as thrown by {@link TreeFilter#include(TreeWalk)}
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
-	 * @throws IOException
+	 *             as thrown by
-	 *             as thrown by {@link TreeFilter#include(TreeWalk)}
+	 *             {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)}
+	 * @throws java.io.IOException
+	 *             as thrown by
+	 *             {@link org.eclipse.jgit.treewalk.filter.TreeFilter#include(TreeWalk)}
 	 */
 	public int getMarks(TreeWalk walk) throws MissingObjectException,
 			IncorrectObjectTypeException, IOException {