Fix javadoc in org.eclipse.jgit dircache package

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

10 files changed, 153 insertions, 92 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java
index 0fbc1f8acf..0228f4d3cc 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/BaseDirCacheEditor.java
@@ -91,6 +91,8 @@ abstract class BaseDirCacheEditor {
 	}
 
 	/**
+	 * Get the {@code DirCache}
+	 *
 	 * @return the cache we will update on {@link #finish()}.
 	 */
 	public DirCache getDirCache() {
@@ -152,7 +154,8 @@ abstract class BaseDirCacheEditor {
 	}
 
 	/**
-	 * Finish this builder and update the destination {@link DirCache}.
+	 * Finish this builder and update the destination
+	 * {@link org.eclipse.jgit.dircache.DirCache}.
 	 * <p>
 	 * When this method completes this builder instance is no longer usable by
 	 * the calling application. A new builder must be created to make additional
@@ -263,9 +266,9 @@ abstract class BaseDirCacheEditor {
 	 * @return true if the commit was successful and the file contains the new
 	 *         data; false if the commit failed and the file remains with the
 	 *         old data.
-	 * @throws IllegalStateException
+	 * @throws java.lang.IllegalStateException
 	 *             the lock is not held.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the output file could not be created. The caller no longer
 	 *             holds the lock.
 	 */
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java
index e00d120735..cc431dbdf2 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCache.java
@@ -158,7 +158,7 @@ public class DirCache {
 	 *            tree to read. Must identify a tree, not a tree-ish.
 	 * @return a new cache which has no backing store file, but contains the
 	 *         contents of {@code treeId}.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             one or more trees not available from the ObjectReader.
 	 * @since 4.2
 	 */
@@ -182,9 +182,9 @@ public class DirCache {
 	 *            repository containing the index to read
 	 * @return a cache representing the contents of the specified index file (if
 	 *         it exists) or an empty cache if the file does not exist.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index file is present but could not be read.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the index file is using a format or extension that this
 	 *             library does not support.
 	 */
@@ -209,9 +209,9 @@ public class DirCache {
 	 *            certain file system operations.
 	 * @return a cache representing the contents of the specified index file (if
 	 *         it exists) or an empty cache if the file does not exist.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index file is present but could not be read.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the index file is using a format or extension that this
 	 *             library does not support.
 	 */
@@ -237,10 +237,10 @@ public class DirCache {
 	 *            certain file system operations.
 	 * @return a cache representing the contents of the specified index file (if
 	 *         it exists) or an empty cache if the file does not exist.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index file is present but could not be read, or the lock
 	 *             could not be obtained.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the index file is using a format or extension that this
 	 *             library does not support.
 	 */
@@ -280,10 +280,10 @@ public class DirCache {
 	 *            listener to be informed when DirCache is committed
 	 * @return a cache representing the contents of the specified index file (if
 	 *         it exists) or an empty cache if the file does not exist.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index file is present but could not be read, or the lock
 	 *             could not be obtained.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the index file is using a format or extension that this
 	 *             library does not support.
 	 * @since 2.0
@@ -314,10 +314,10 @@ public class DirCache {
 	 *            listener to be informed when DirCache is committed
 	 * @return a cache representing the contents of the specified index file (if
 	 *         it exists) or an empty cache if the file does not exist.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index file is present but could not be read, or the lock
 	 *             could not be obtained.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the index file is using a format or extension that this
 	 *             library does not support.
 	 */
@@ -381,7 +381,8 @@ public class DirCache {
 	 * Create a new builder to update this cache.
 	 * <p>
 	 * Callers should add all entries to the builder, then use
-	 * {@link DirCacheBuilder#finish()} to update this instance.
+	 * {@link org.eclipse.jgit.dircache.DirCacheBuilder#finish()} to update this
+	 * instance.
 	 *
 	 * @return a new builder instance for this cache.
 	 */
@@ -393,7 +394,8 @@ public class DirCache {
 	 * Create a new editor to recreate this cache.
 	 * <p>
 	 * Callers should add commands to the editor, then use
-	 * {@link DirCacheEditor#finish()} to update this instance.
+	 * {@link org.eclipse.jgit.dircache.DirCacheEditor#finish()} to update this
+	 * instance.
 	 *
 	 * @return a new builder instance for this cache.
 	 */
@@ -414,10 +416,10 @@ public class DirCache {
 	 * the last time we consulted it. A missing index file will be treated as
 	 * though it were present but had no file entries in it.
 	 *
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the index file is present but could not be read. This
 	 *             DirCache instance may not be populated correctly.
-	 * @throws CorruptObjectException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
 	 *             the index file is using a format or extension that this
 	 *             library does not support.
 	 */
@@ -456,8 +458,10 @@ public class DirCache {
 	}
 
 	/**
-	 * @return true if the memory state differs from the index file
-	 * @throws IOException
+	 * Whether the memory state differs from the index file
+	 *
+	 * @return {@code true} if the memory state differs from the index file
+	 * @throws java.io.IOException
 	 */
 	public boolean isOutdated() throws IOException {
 		if (liveFile == null || !liveFile.exists())
@@ -465,7 +469,9 @@ public class DirCache {
 		return snapshot == null || snapshot.isModified(liveFile);
 	}
 
-	/** Empty this index, removing all entries. */
+	/**
+	 * Empty this index, removing all entries.
+	 */
 	public void clear() {
 		snapshot = null;
 		sortedEntries = NO_ENTRIES;
@@ -601,7 +607,7 @@ public class DirCache {
 	 *
 	 * @return true if the lock is now held by the caller; false if it is held
 	 *         by someone else.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the output file could not be created. The caller does not
 	 *             hold the lock.
 	 */
@@ -628,7 +634,7 @@ public class DirCache {
 	 * Once written the lock is closed and must be either committed with
 	 * {@link #commit()} or rolled back with {@link #unlock()}.
 	 *
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             the output file could not be created. The caller no longer
 	 *             holds the lock.
 	 */
@@ -730,7 +736,7 @@ public class DirCache {
 	 * @return true if the commit was successful and the file contains the new
 	 *         data; false if the commit failed and the file remains with the
 	 *         old data.
-	 * @throws IllegalStateException
+	 * @throws java.lang.IllegalStateException
 	 *             the lock is not held.
 	 */
 	public boolean commit() {
@@ -957,13 +963,13 @@ public class DirCache {
 	 *            responsible for flushing the inserter before trying to use the
 	 *            returned tree identity.
 	 * @return identity for the root tree.
-	 * @throws UnmergedPathException
+	 * @throws org.eclipse.jgit.errors.UnmergedPathException
 	 *             one or more paths contain higher-order stages (stage &gt; 0),
 	 *             which cannot be stored in a tree object.
-	 * @throws IllegalStateException
+	 * @throws java.lang.IllegalStateException
 	 *             one or more paths contain an invalid mode which should never
 	 *             appear in a tree object.
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             an unexpected error occurred writing to the object store.
 	 */
 	public ObjectId writeTree(final ObjectInserter ow)
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java
index c10e416082..6e3682a3e2 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuildIterator.java
@@ -54,12 +54,14 @@ import org.eclipse.jgit.lib.ObjectReader;
 import org.eclipse.jgit.treewalk.AbstractTreeIterator;
 
 /**
- * Iterate and update a {@link DirCache} as part of a <code>TreeWalk</code>.
+ * Iterate and update a {@link org.eclipse.jgit.dircache.DirCache} as part of a
+ * <code>TreeWalk</code>.
  * <p>
- * Like {@link DirCacheIterator} this iterator allows a DirCache to be used in
- * parallel with other sorts of iterators in a TreeWalk. However any entry which
- * appears in the source DirCache and which is skipped by the TreeFilter is
- * automatically copied into {@link DirCacheBuilder}, thus retaining it in the
+ * Like {@link org.eclipse.jgit.dircache.DirCacheIterator} this iterator allows
+ * a DirCache to be used in parallel with other sorts of iterators in a
+ * TreeWalk. However any entry which appears in the source DirCache and which is
+ * skipped by the TreeFilter is automatically copied into
+ * {@link org.eclipse.jgit.dircache.DirCacheBuilder}, thus retaining it in the
  * newly updated index.
  * <p>
  * This iterator is suitable for update processes, or even a simple delete
@@ -105,6 +107,7 @@ public class DirCacheBuildIterator extends DirCacheIterator {
 		builder = p.builder;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader)
 			throws IncorrectObjectTypeException, IOException {
@@ -114,6 +117,7 @@ public class DirCacheBuildIterator extends DirCacheIterator {
 		return new DirCacheBuildIterator(this, currentSubtree);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void skip() throws CorruptObjectException {
 		if (currentSubtree != null)
@@ -123,6 +127,7 @@ public class DirCacheBuildIterator extends DirCacheIterator {
 		next(1);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void stopWalk() {
 		final int cur = ptr;
@@ -131,6 +136,7 @@ public class DirCacheBuildIterator extends DirCacheIterator {
 			builder.keep(cur, cnt - cur);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	protected boolean needsStopWalk() {
 		return ptr < cache.getEntryCount();
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java
index 676a6ab9c4..2ff7bb9aea 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheBuilder.java
@@ -57,7 +57,8 @@ import org.eclipse.jgit.lib.ObjectReader;
 import org.eclipse.jgit.treewalk.CanonicalTreeParser;
 
 /**
- * Updates a {@link DirCache} by adding individual {@link DirCacheEntry}s.
+ * Updates a {@link org.eclipse.jgit.dircache.DirCache} by adding individual
+ * {@link org.eclipse.jgit.dircache.DirCacheEntry}s.
  * <p>
  * A builder always starts from a clean slate and appends in every single
  * <code>DirCacheEntry</code> which the final updated index must have to reflect
@@ -98,7 +99,7 @@ public class DirCacheBuilder extends BaseDirCacheEditor {
 	 *
 	 * @param newEntry
 	 *            the new entry to add.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             If the FileMode of the entry was not set by the caller.
 	 */
 	public void add(final DirCacheEntry newEntry) {
@@ -161,7 +162,7 @@ public class DirCacheBuilder extends BaseDirCacheEditor {
 	 *            under <code>pathPrefix</code>. The ObjectId must be that of a
 	 *            tree; the caller is responsible for dereferencing a tag or
 	 *            commit (if necessary).
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 *             a tree cannot be read to iterate through its entries.
 	 */
 	public void addTree(byte[] pathPrefix, int stage, ObjectReader reader,
@@ -218,6 +219,7 @@ public class DirCacheBuilder extends BaseDirCacheEditor {
 		return e;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void finish() {
 		if (!sorted)
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java
index d3d8cd8ee3..d41a1f57fb 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheCheckout.java
@@ -159,6 +159,8 @@ public class DirCacheCheckout {
 	private boolean performingCheckout;
 
 	/**
+	 * Get list of updated paths and smudgeFilterCommands
+	 *
 	 * @return a list of updated paths and smudgeFilterCommands
 	 */
 	public Map<String, CheckoutMetadata> getUpdated() {
@@ -166,6 +168,8 @@ public class DirCacheCheckout {
 	}
 
 	/**
+	 * Get a list of conflicts created by this checkout
+	 *
 	 * @return a list of conflicts created by this checkout
 	 */
 	public List<String> getConflicts() {
@@ -173,19 +177,24 @@ public class DirCacheCheckout {
 	}
 
 	/**
+	 * Get list of paths of files which couldn't be deleted during last call to
+	 * {@link #checkout()}
+	 *
 	 * @return a list of paths (relative to the start of the working tree) of
 	 *         files which couldn't be deleted during last call to
 	 *         {@link #checkout()} . {@link #checkout()} detected that these
 	 *         files should be deleted but the deletion in the filesystem failed
 	 *         (e.g. because a file was locked). To have a consistent state of
 	 *         the working tree these files have to be deleted by the callers of
-	 *         {@link DirCacheCheckout}.
+	 *         {@link org.eclipse.jgit.dircache.DirCacheCheckout}.
 	 */
 	public List<String> getToBeDeleted() {
 		return toBeDeleted;
 	}
 
 	/**
+	 * Get list of all files removed by this checkout
+	 *
 	 * @return a list of all files removed by this checkout
 	 */
 	public List<String> getRemoved() {
@@ -206,7 +215,7 @@ public class DirCacheCheckout {
 	 *            the id of the tree we want to fast-forward to
 	 * @param workingTree
 	 *            an iterator over the repositories Working Tree
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public DirCacheCheckout(Repository repo, ObjectId headCommitTree, DirCache dc,
 			ObjectId mergeCommitTree, WorkingTreeIterator workingTree)
@@ -222,7 +231,8 @@ public class DirCacheCheckout {
 	/**
 	 * Constructs a DirCacheCeckout for merging and checking out two trees (HEAD
 	 * and mergeCommitTree) and the index. As iterator over the working tree
-	 * this constructor creates a standard {@link FileTreeIterator}
+	 * this constructor creates a standard
+	 * {@link org.eclipse.jgit.treewalk.FileTreeIterator}
 	 *
 	 * @param repo
 	 *            the repository in which we do the checkout
@@ -232,7 +242,7 @@ public class DirCacheCheckout {
 	 *            the (already locked) Dircache for this repo
 	 * @param mergeCommitTree
 	 *            the id of the tree we want to fast-forward to
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public DirCacheCheckout(Repository repo, ObjectId headCommitTree,
 			DirCache dc, ObjectId mergeCommitTree) throws IOException {
@@ -251,7 +261,7 @@ public class DirCacheCheckout {
 	 *            the id of the tree we want to fast-forward to
 	 * @param workingTree
 	 *            an iterator over the repositories Working Tree
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public DirCacheCheckout(Repository repo, DirCache dc,
 			ObjectId mergeCommitTree, WorkingTreeIterator workingTree)
@@ -262,7 +272,7 @@ public class DirCacheCheckout {
 	/**
 	 * Constructs a DirCacheCeckout for checking out one tree, merging with the
 	 * index. As iterator over the working tree this constructor creates a
-	 * standard {@link FileTreeIterator}
+	 * standard {@link org.eclipse.jgit.treewalk.FileTreeIterator}
 	 *
 	 * @param repo
 	 *            the repository in which we do the checkout
@@ -270,7 +280,7 @@ public class DirCacheCheckout {
 	 *            the (already locked) Dircache for this repo
 	 * @param mergeCommitTree
 	 *            the id of the tree of the
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public DirCacheCheckout(Repository repo, DirCache dc,
 			ObjectId mergeCommitTree) throws IOException {
@@ -281,8 +291,8 @@ public class DirCacheCheckout {
 	 * Scan head, index and merge tree. Used during normal checkout or merge
 	 * operations.
 	 *
-	 * @throws CorruptObjectException
-	 * @throws IOException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
+	 * @throws java.io.IOException
 	 */
 	public void preScanTwoTrees() throws CorruptObjectException, IOException {
 		removed.clear();
@@ -318,10 +328,10 @@ public class DirCacheCheckout {
 	 * Scan index and merge tree (no HEAD). Used e.g. for initial checkout when
 	 * there is no head yet.
 	 *
-	 * @throws MissingObjectException
-	 * @throws IncorrectObjectTypeException
-	 * @throws CorruptObjectException
-	 * @throws IOException
+	 * @throws org.eclipse.jgit.errors.MissingObjectException
+	 * @throws org.eclipse.jgit.errors.IncorrectObjectTypeException
+	 * @throws org.eclipse.jgit.errors.CorruptObjectException
+	 * @throws java.io.IOException
 	 */
 	public void prescanOneTree()
 			throws MissingObjectException, IncorrectObjectTypeException,
@@ -439,7 +449,8 @@ public class DirCacheCheckout {
 	}
 
 	/**
-	 * Execute this checkout. A {@link WorkingTreeModifiedEvent} is fired if the
+	 * Execute this checkout. A
+	 * {@link org.eclipse.jgit.events.WorkingTreeModifiedEvent} is fired if the
 	 * working tree was modified; even if the checkout fails.
 	 *
 	 * @return <code>false</code> if this method could not delete all the files
@@ -449,8 +460,7 @@ public class DirCacheCheckout {
 	 *         Although <code>false</code> is returned the checkout was
 	 *         successful and the working tree was updated for all other files.
 	 *         <code>true</code> is returned when no such problem occurred
-	 *
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 */
 	public boolean checkout() throws IOException {
 		try {
@@ -1163,10 +1173,12 @@ public class DirCacheCheckout {
 
 	/**
 	 * If <code>true</code>, will scan first to see if it's possible to check
-	 * out, otherwise throw {@link CheckoutConflictException}. If
+	 * out, otherwise throw
+	 * {@link org.eclipse.jgit.errors.CheckoutConflictException}. If
 	 * <code>false</code>, it will silently deal with the problem.
 	 *
 	 * @param failOnConflict
+	 *            a boolean.
 	 */
 	public void setFailOnConflict(boolean failOnConflict) {
 		this.failOnConflict = failOnConflict;
@@ -1286,8 +1298,8 @@ public class DirCacheCheckout {
 	 * <p>
 	 * <b>Note:</b> if the entry path on local file system exists as a non-empty
 	 * directory, and the target entry type is a link or file, the checkout will
-	 * fail with {@link IOException} since existing non-empty directory cannot
-	 * be renamed to file or link without deleting it recursively.
+	 * fail with {@link java.io.IOException} since existing non-empty directory
+	 * cannot be renamed to file or link without deleting it recursively.
 	 * </p>
 	 *
 	 * <p>
@@ -1302,7 +1314,7 @@ public class DirCacheCheckout {
 	 *            the entry containing new mode and content
 	 * @param or
 	 *            object reader to use for checkout
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 * @since 3.6
 	 */
 	public static void checkoutEntry(Repository repo, DirCacheEntry entry,
@@ -1344,8 +1356,7 @@ public class DirCacheCheckout {
 	 *            checked out</li>
 	 *            <li>eolStreamType used for stream conversion</li>
 	 *            </ul>
-	 *
-	 * @throws IOException
+	 * @throws java.io.IOException
 	 * @since 4.2
 	 */
 	public static void checkoutEntry(Repository repo, DirCacheEntry entry,
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java
index 22bedcf91b..30e3a3cf12 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEditor.java
@@ -60,14 +60,16 @@ import org.eclipse.jgit.lib.Constants;
 import org.eclipse.jgit.util.Paths;
 
 /**
- * Updates a {@link DirCache} by supplying discrete edit commands.
+ * Updates a {@link org.eclipse.jgit.dircache.DirCache} by supplying discrete
+ * edit commands.
  * <p>
- * An editor updates a DirCache by taking a list of {@link PathEdit} commands
- * and executing them against the entries of the destination cache to produce a
- * new cache. This edit style allows applications to insert a few commands and
- * then have the editor compute the proper entry indexes necessary to perform an
+ * An editor updates a DirCache by taking a list of
+ * {@link org.eclipse.jgit.dircache.DirCacheEditor.PathEdit} commands and
+ * executing them against the entries of the destination cache to produce a new
+ * cache. This edit style allows applications to insert a few commands and then
+ * have the editor compute the proper entry indexes necessary to perform an
  * efficient in-order update of the index records. This can be easier to use
- * than {@link DirCacheBuilder}.
+ * than {@link org.eclipse.jgit.dircache.DirCacheBuilder}.
  * <p>
  *
  * @see DirCacheBuilder
@@ -113,6 +115,7 @@ public class DirCacheEditor extends BaseDirCacheEditor {
 		edits.add(edit);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean commit() throws IOException {
 		if (edits.isEmpty()) {
@@ -124,6 +127,7 @@ public class DirCacheEditor extends BaseDirCacheEditor {
 		return super.commit();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void finish() {
 		if (!edits.isEmpty()) {
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java
index 4ebf2e0d71..7c03c64946 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheEntry.java
@@ -68,7 +68,8 @@ import org.eclipse.jgit.util.NB;
 import org.eclipse.jgit.util.SystemReader;
 
 /**
- * A single file (or stage of a file) in a {@link DirCache}.
+ * A single file (or stage of a file) in a
+ * {@link org.eclipse.jgit.dircache.DirCache}.
  * <p>
  * An entry represents exactly one stage of a file. If a file path is unmerged
  * then multiple DirCacheEntry instances may appear for the same path name.
@@ -221,7 +222,7 @@ public class DirCacheEntry {
 	 *
 	 * @param newPath
 	 *            name of the cache entry.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             If the path starts or ends with "/", or contains "//" either
 	 *             "\0". These sequences are not permitted in a git tree object
 	 *             or DirCache file.
@@ -237,7 +238,7 @@ public class DirCacheEntry {
 	 *            name of the cache entry.
 	 * @param stage
 	 *            the stage index of the new entry.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             If the path starts or ends with "/", or contains "//" either
 	 *             "\0". These sequences are not permitted in a git tree object
 	 *             or DirCache file.  Or if {@code stage} is outside of the
@@ -252,7 +253,7 @@ public class DirCacheEntry {
 	 *
 	 * @param newPath
 	 *            name of the cache entry, in the standard encoding.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             If the path starts or ends with "/", or contains "//" either
 	 *             "\0". These sequences are not permitted in a git tree object
 	 *             or DirCache file.
@@ -268,7 +269,7 @@ public class DirCacheEntry {
 	 *            name of the cache entry, in the standard encoding.
 	 * @param stage
 	 *            the stage index of the new entry.
-	 * @throws IllegalArgumentException
+	 * @throws java.lang.IllegalArgumentException
 	 *             If the path starts or ends with "/", or contains "//" either
 	 *             "\0". These sequences are not permitted in a git tree object
 	 *             or DirCache file.  Or if {@code stage} is outside of the
@@ -378,8 +379,9 @@ public class DirCacheEntry {
 	/**
 	 * Check whether this entry has been smudged or not
 	 * <p>
-	 * If a blob has length 0 we know his id see {@link Constants#EMPTY_BLOB_ID}. If an entry
-	 * has length 0 and an ID different from the one for empty blob we know this
+	 * If a blob has length 0 we know its id, see
+	 * {@link org.eclipse.jgit.lib.Constants#EMPTY_BLOB_ID}. If an entry has
+	 * length 0 and an ID different from the one for empty blob we know this
 	 * entry was smudged.
 	 *
 	 * @return <code>true</code> if the entry is smudged, <code>false</code>
@@ -426,7 +428,9 @@ public class DirCacheEntry {
 	}
 
 	/**
-	 * @return true if this entry should be checked for changes
+	 * Whether this entry should be checked for changes
+	 *
+	 * @return {@code true} if this entry should be checked for changes
 	 */
 	public boolean isUpdateNeeded() {
 		return (inCoreFlags & UPDATE_NEEDED) != 0;
@@ -436,6 +440,7 @@ public class DirCacheEntry {
 	 * Set whether this entry must be checked for changes
 	 *
 	 * @param updateNeeded
+	 *            whether this entry must be checked for changes
 	 */
 	public void setUpdateNeeded(boolean updateNeeded) {
 		if (updateNeeded)
@@ -484,7 +489,7 @@ public class DirCacheEntry {
 	}
 
 	/**
-	 * Obtain the raw {@link FileMode} bits for this entry.
+	 * Obtain the raw {@link org.eclipse.jgit.lib.FileMode} bits for this entry.
 	 *
 	 * @return mode bits for the entry.
 	 * @see FileMode#fromBits(int)
@@ -494,7 +499,7 @@ public class DirCacheEntry {
 	}
 
 	/**
-	 * Obtain the {@link FileMode} for this entry.
+	 * Obtain the {@link org.eclipse.jgit.lib.FileMode} for this entry.
 	 *
 	 * @return the file mode singleton for this entry.
 	 */
@@ -507,10 +512,11 @@ public class DirCacheEntry {
 	 *
 	 * @param mode
 	 *            the new mode constant.
-	 * @throws IllegalArgumentException
-	 *             If {@code mode} is {@link FileMode#MISSING},
-	 *             {@link FileMode#TREE}, or any other type code not permitted
-	 *             in a tree object.
+	 * @throws java.lang.IllegalArgumentException
+	 *             If {@code mode} is
+	 *             {@link org.eclipse.jgit.lib.FileMode#MISSING},
+	 *             {@link org.eclipse.jgit.lib.FileMode#TREE}, or any other type
+	 *             code not permitted in a tree object.
 	 */
 	public void setFileMode(final FileMode mode) {
 		switch (mode.getBits() & FileMode.TYPE_MASK) {
@@ -629,7 +635,8 @@ public class DirCacheEntry {
 	 *
 	 * @param id
 	 *            new object identifier for the entry. May be
-	 *            {@link ObjectId#zeroId()} to remove the current identifier.
+	 *            {@link org.eclipse.jgit.lib.ObjectId#zeroId()} to remove the
+	 *            current identifier.
 	 */
 	public void setObjectId(final AnyObjectId id) {
 		id.copyRawTo(idBuffer(), idOffset());
@@ -676,6 +683,8 @@ public class DirCacheEntry {
 	}
 
 	/**
+	 * {@inheritDoc}
+	 * <p>
 	 * Use for debugging only !
 	 */
 	@SuppressWarnings("nls")
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java
index ad93f7213f..68521d3981 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java
@@ -61,7 +61,8 @@ import org.eclipse.jgit.treewalk.EmptyTreeIterator;
 import org.eclipse.jgit.util.RawParseUtils;
 
 /**
- * Iterate a {@link DirCache} as part of a <code>TreeWalk</code>.
+ * Iterate a {@link org.eclipse.jgit.dircache.DirCache} as part of a
+ * <code>TreeWalk</code>.
  * <p>
  * This is an iterator to adapt a loaded <code>DirCache</code> instance (such as
  * read from an existing <code>.git/index</code> file) to the tree structure
@@ -134,6 +135,7 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		parseEntry();
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public AbstractTreeIterator createSubtreeIterator(final ObjectReader reader)
 			throws IncorrectObjectTypeException, IOException {
@@ -143,6 +145,7 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		return new DirCacheIterator(this, currentSubtree);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public EmptyTreeIterator createEmptyTreeIterator() {
 		final byte[] n = new byte[Math.max(pathLen + 1, DEFAULT_PATH_SIZE)];
@@ -151,6 +154,7 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		return new EmptyTreeIterator(this, n, pathLen + 1);
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean hasId() {
 		if (currentSubtree != null)
@@ -158,6 +162,7 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		return currentEntry != null;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public byte[] idBuffer() {
 		if (currentSubtree != null)
@@ -167,6 +172,7 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		return zeroid;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public int idOffset() {
 		if (currentSubtree != null)
@@ -176,6 +182,7 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		return 0;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void reset() {
 		if (!first()) {
@@ -188,16 +195,19 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean first() {
 		return ptr == treeStart;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public boolean eof() {
 		return ptr == treeEnd;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void next(int delta) {
 		while (--delta >= 0) {
@@ -211,6 +221,7 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		}
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public void back(int delta) {
 		while (--delta >= 0) {
@@ -282,12 +293,15 @@ public class DirCacheIterator extends AbstractTreeIterator {
 	}
 
 	/**
-	 * Retrieves the {@link AttributesNode} for the current entry.
+	 * Retrieves the {@link org.eclipse.jgit.attributes.AttributesNode} for the
+	 * current entry.
 	 *
 	 * @param reader
-	 *            {@link ObjectReader} used to parse the .gitattributes entry.
-	 * @return {@link AttributesNode} for the current entry.
-	 * @throws IOException
+	 *            {@link org.eclipse.jgit.lib.ObjectReader} used to parse the
+	 *            .gitattributes entry.
+	 * @return {@link org.eclipse.jgit.attributes.AttributesNode} for the
+	 *         current entry.
+	 * @throws java.io.IOException
 	 * @since 3.7
 	 */
 	public AttributesNode getEntryAttributesNode(ObjectReader reader)
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java
index a06f9d3f4f..dc825d4dc7 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheTree.java
@@ -62,13 +62,14 @@ import org.eclipse.jgit.util.MutableInteger;
 import org.eclipse.jgit.util.RawParseUtils;
 
 /**
- * Single tree record from the 'TREE' {@link DirCache} extension.
+ * Single tree record from the 'TREE' {@link org.eclipse.jgit.dircache.DirCache}
+ * extension.
  * <p>
  * A valid cache tree record contains the object id of a tree object and the
- * total number of {@link DirCacheEntry} instances (counted recursively) from
- * the DirCache contained within the tree. This information facilitates faster
- * traversal of the index and quicker generation of tree objects prior to
- * creating a new commit.
+ * total number of {@link org.eclipse.jgit.dircache.DirCacheEntry} instances
+ * (counted recursively) from the DirCache contained within the tree. This
+ * information facilitates faster traversal of the index and quicker generation
+ * of tree objects prior to creating a new commit.
  * <p>
  * An invalid cache tree record indicates a known subtree whose file entries
  * have changed in ways that cause the tree to no longer have a known object id.
@@ -205,10 +206,11 @@ public class DirCacheTree {
 	/**
 	 * Determine if this cache is currently valid.
 	 * <p>
-	 * A valid cache tree knows how many {@link DirCacheEntry} instances from
-	 * the parent {@link DirCache} reside within this tree (recursively
-	 * enumerated). It also knows the object id of the tree, as the tree should
-	 * be readily available from the repository's object database.
+	 * A valid cache tree knows how many
+	 * {@link org.eclipse.jgit.dircache.DirCacheEntry} instances from the parent
+	 * {@link org.eclipse.jgit.dircache.DirCache} reside within this tree
+	 * (recursively enumerated). It also knows the object id of the tree, as the
+	 * tree should be readily available from the repository's object database.
 	 *
 	 * @return true if this tree is knows key details about itself; false if the
 	 *         tree needs to be regenerated.
@@ -563,6 +565,7 @@ public class DirCacheTree {
 		return -1;
 	}
 
+	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		return getNameString();
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java
index 50d1c4ca38..7e81b8b037 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/InvalidPathException.java
@@ -57,7 +57,10 @@ public class InvalidPathException extends IllegalArgumentException {
 	private static final long serialVersionUID = 1L;
 
 	/**
+	 * Constructor for InvalidPathException
+	 *
 	 * @param path
+	 *            the invalid path
 	 */
 	public InvalidPathException(String path) {
 		this(JGitText.get().invalidPath, path);