Fix all Javadoc warnings and fail on them

This fixes all the javadoc warnings, stops ignoring doclint 'missing'
category and fails the build on javadoc warnings for public and
protected classes and class members.

Since javadoc doesn't allow access specifiers when specifying doclint
configuration we cannot set `-Xdoclint:all,-missing/private`
hence there is no simple way to skip private elements from doclint.
Therefore we check javadoc using the Eclipse Java compiler
(which is used by default) and javadoc configuration in
`.settings/org.eclipse.jdt.core.prefs` files.
This allows more fine grained configuration.

We can reconsider this when javadoc starts supporting access specifiers
in the doclint configuration.

Below are detailled explanations for most modifications.

@inheritDoc
===========
doclint complains about explicits `{@inheritDoc}` when the parent does
not have any documentation. As far as I can tell, javadoc defaults to
inherit comments and should only be used when one wants to append extra
documentation from the parent. Given the parent has no documentation,
remove those usages which doclint complains about.

In some case I have moved up the documentation from the concrete class
up to the abstract class.

Remove `{@inheritDoc}` on overriden methods which don't add additional
documentation since javadoc defaults to inherit javadoc of overridden
methods.

@value to @link
===============
In PackConfig, DEFAULT_SEARCH_FOR_REUSE_TIMEOUT and similar are forged
from Integer.MAX_VALUE and are thus not considered constants (I guess
cause the value would depends on the platform). Replace it with a link
to `Integer.MAX_VALUE`.

In `StringUtils.toBoolean`, @value was used to refer to the
`stringValue` parameter. I have replaced it with `{@code stringValue}`.

{@link <url>} to <a>
====================
@link does not support being given an external URL. Replaces them with
HTML `<a>`.

@since: being invalid
=====================

org.eclipse.jgit/src/org/eclipse/jgit/util/Equality.java has an invalid
tag `@since: ` due to the extra `:`. Javadoc does not complain about it
with version 11.0.18+10 but does with 11.0.19.7. It is invalid
regardless.

invalid HTML syntax
===================

- javadoc doesn't allow <br/>, <p/> and </p> anymore, use <br> and <p>
instead
- replace <tt>code</tt> by {@code code}
- <table> tags don't allow summary attribute, specify caption as
<caption>caption</caption> to fix this

doclint visibility issue
========================

In the private abstract classes `BaseDirCacheEditor` and
`BasePackConnection` links to other methods in the abstract class are
inherited in the public subclasses but doclint gets confused and
considers them unreachable. The HTML documentation for the sub classes
shows the relative links in the sub classes, so it is all correct. It
must be a bug somewhere in javadoc.
Mute those warnings with: @SuppressWarnings("doclint:missing")

Misc
====
Replace `<` and `>` with HTML encoded entities (`&lt; and `&gt;`).
In `SshConstants` I went enclosing a serie of -> arrows in @literal.

Additional tags
===============
Configure maven-javad0c-plugin to allow the following additional tags
defined in https://openjdk.org/jeps/8068562:
- apiNote
- implSpec
- implNote

Missing javadoc
===============
Add missing @params and descriptions

Change-Id: I840056389aa59135cfb360da0d5e40463ce35bd0
Also-By: Matthias Sohn <matthias.sohn@sap.com>

9 files changed, 130 insertions, 36 deletions

diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/JGitTestUtil.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/JGitTestUtil.java
index 61d3b860e9..177d8737cb 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/JGitTestUtil.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/JGitTestUtil.java
@@ -107,6 +107,7 @@ public abstract class JGitTestUtil {
 	 * Get test resource file.
 	 *
 	 * @param fileName
+	 *            file name
 	 * @return the test resource file
 	 */
 	public static File getTestResourceFile(String fileName) {
@@ -141,8 +142,11 @@ public abstract class JGitTestUtil {
 	 * Copy test resource.
 	 *
 	 * @param name
+	 *            resource name
 	 * @param dest
+	 *            destination file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static void copyTestResource(String name, File dest)
 			throws IOException {
@@ -165,10 +169,14 @@ public abstract class JGitTestUtil {
 	 * Write a trash file.
 	 *
 	 * @param db
+	 *            the repository
 	 * @param name
+	 *            file name
 	 * @param data
+	 *            file content
 	 * @return the trash file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static File writeTrashFile(final Repository db,
 			final String name, final String data) throws IOException {
@@ -181,11 +189,16 @@ public abstract class JGitTestUtil {
 	 * Write a trash file.
 	 *
 	 * @param db
+	 *            the repository
 	 * @param subdir
+	 *            under working tree
 	 * @param name
+	 *            file name
 	 * @param data
+	 *            file content
 	 * @return the trash file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static File writeTrashFile(final Repository db,
 			final String subdir,
@@ -237,9 +250,12 @@ public abstract class JGitTestUtil {
 	 * Read a file's content
 	 *
 	 * @param db
+	 *            the repository
 	 * @param name
+	 *            file name
 	 * @return the content of the file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static String read(Repository db, String name)
 			throws IOException {
@@ -251,6 +267,7 @@ public abstract class JGitTestUtil {
 	 * Check if file exists
 	 *
 	 * @param db
+	 *            the repository
 	 * @param name
 	 *            name of the file
 	 * @return {@code true} if the file exists
@@ -264,8 +281,11 @@ public abstract class JGitTestUtil {
 	 * Delete a trash file.
 	 *
 	 * @param db
+	 *            the repository
 	 * @param name
+	 *            file name
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static void deleteTrashFile(final Repository db,
 			final String name) throws IOException {
@@ -284,6 +304,7 @@ public abstract class JGitTestUtil {
 	 *            the target of the symbolic link
 	 * @return the path to the symbolic link
 	 * @throws Exception
+	 *             if an error occurred
 	 * @since 4.2
 	 */
 	public static Path writeLink(Repository db, String link,
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/LocalDiskRepositoryTestCase.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/LocalDiskRepositoryTestCase.java
index 59662cec95..0945327ab3 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/LocalDiskRepositoryTestCase.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/LocalDiskRepositoryTestCase.java
@@ -107,6 +107,7 @@ public abstract class LocalDiskRepositoryTestCase {
 	 * Setup test
 	 *
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	@Before
 	public void setUp() throws Exception {
@@ -189,6 +190,7 @@ public abstract class LocalDiskRepositoryTestCase {
 	 * Tear down the test
 	 *
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	@After
 	public void tearDown() throws Exception {
@@ -314,11 +316,11 @@ public abstract class LocalDiskRepositoryTestCase {
 	 *            {@link #CONTENT} controlling which info is present in the
 	 *            resulting string.
 	 * @return a string encoding the index state
-	 * @throws IllegalStateException
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static String indexState(Repository repo, int includedOptions)
-			throws IllegalStateException, IOException {
+			throws IOException {
 		DirCache dc = repo.readDirCache();
 		StringBuilder sb = new StringBuilder();
 		TreeSet<Instant> timeStamps = new TreeSet<>();
@@ -452,6 +454,7 @@ public abstract class LocalDiskRepositoryTestCase {
 	 *            a subdirectory
 	 * @return a unique directory for a test
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected File createTempDirectory(String name) throws IOException {
 		File directory = new File(createTempFile(), name);
@@ -467,6 +470,7 @@ public abstract class LocalDiskRepositoryTestCase {
 	 *            working directory
 	 * @return a unique directory for a test repository
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected File createUniqueTestGitDir(boolean bare) throws IOException {
 		String gitdirName = createTempFile().getPath();
@@ -487,6 +491,7 @@ public abstract class LocalDiskRepositoryTestCase {
 	 *
 	 * @return a unique path that does not exist.
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected File createTempFile() throws IOException {
 		File p = File.createTempFile("tmp_", "", tmp);
@@ -586,6 +591,7 @@ public abstract class LocalDiskRepositoryTestCase {
 	 *            the file
 	 * @return the content of the file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected String read(File f) throws IOException {
 		return JGitTestUtil.read(f);
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/MockSystemReader.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/MockSystemReader.java
index 6bfe70659b..4dbfc59ec7 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/MockSystemReader.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/MockSystemReader.java
@@ -144,32 +144,30 @@ public class MockSystemReader extends SystemReader {
 	 * Set a property
 	 *
 	 * @param key
+	 *            the key
 	 * @param value
+	 *            the value
 	 */
 	public void setProperty(String key, String value) {
 		values.put(key, value);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getenv(String variable) {
 		return values.get(variable);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getProperty(String key) {
 		return values.get(key);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public FileBasedConfig openUserConfig(Config parent, FS fs) {
 		assert parent == null || parent == systemGitConfig;
 		return userGitConfig;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public FileBasedConfig openSystemConfig(Config parent, FS fs) {
 		assert parent == null;
@@ -193,19 +191,16 @@ public class MockSystemReader extends SystemReader {
 		return systemGitConfig;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getHostname() {
 		return "fake.host.example.com";
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public long getCurrentTime() {
 		return now;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public MonotonicClock getClock() {
 		return () -> {
@@ -236,31 +231,26 @@ public class MockSystemReader extends SystemReader {
 		now += secDelta * 1000L;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public int getTimezone(long when) {
 		return getTimeZone().getOffset(when) / (60 * 1000);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public TimeZone getTimeZone() {
 		return TimeZone.getTimeZone("GMT-03:30");
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public Locale getLocale() {
 		return Locale.US;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public SimpleDateFormat getSimpleDateFormat(String pattern) {
 		return new SimpleDateFormat(pattern, getLocale());
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public DateFormat getDateTimeInstance(int dateStyle, int timeStyle) {
 		return DateFormat
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/Repeat.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/Repeat.java
index 343aa92f8a..4bf2eb59da 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/Repeat.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/Repeat.java
@@ -21,6 +21,8 @@ import java.lang.annotation.Target;
 public @interface Repeat {
 	/**
 	 * Number of repetitions
+	 *
+	 * @return number of repetitions
 	 */
 	public abstract int n();
 
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepeatRule.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepeatRule.java
index adcc10cad8..30fffe9d94 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepeatRule.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepeatRule.java
@@ -125,7 +125,6 @@ public class RepeatRule implements TestRule {
 		}
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public Statement apply(Statement statement, Description description) {
 		Statement result = statement;
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepositoryTestCase.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepositoryTestCase.java
index 04988f6289..3a283ce10d 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepositoryTestCase.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/RepositoryTestCase.java
@@ -62,8 +62,11 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Copy a file
 	 *
 	 * @param src
+	 *            file to copy
 	 * @param dst
+	 *            destination of the copy
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected static void copyFile(File src, File dst)
 			throws IOException {
@@ -81,9 +84,12 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Write a trash file
 	 *
 	 * @param name
+	 *            file name
 	 * @param data
+	 *            file content
 	 * @return the trash file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected File writeTrashFile(String name, String data)
 			throws IOException {
@@ -99,6 +105,7 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 *            the target of the symbolic link
 	 * @return the path to the symbolic link
 	 * @throws Exception
+	 *             if an error occurred
 	 * @since 4.2
 	 */
 	protected Path writeLink(String link, String target)
@@ -110,10 +117,14 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Write a trash file
 	 *
 	 * @param subdir
+	 *            in working tree
 	 * @param name
+	 *            file name
 	 * @param data
+	 *            file content
 	 * @return the trash file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected File writeTrashFile(final String subdir, final String name,
 			final String data)
@@ -125,8 +136,10 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Read content of a file
 	 *
 	 * @param name
+	 *            file name
 	 * @return the file's content
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected String read(String name) throws IOException {
 		return JGitTestUtil.read(db, name);
@@ -149,6 +162,7 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * @param name
 	 *            file name
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected void deleteTrashFile(String name) throws IOException {
 		JGitTestUtil.deleteTrashFile(db, name);
@@ -158,9 +172,11 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Check content of a file.
 	 *
 	 * @param f
+	 *            file
 	 * @param checkData
 	 *            expected content
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected static void checkFile(File f, String checkData)
 			throws IOException {
@@ -181,7 +197,6 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	/** Working directory of {@link #db}. */
 	protected File trash;
 
-	/** {@inheritDoc} */
 	@Override
 	@Before
 	public void setUp() throws Exception {
@@ -229,11 +244,11 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 *            {@link #CONTENT} controlling which info is present in the
 	 *            resulting string.
 	 * @return a string encoding the index state
-	 * @throws IllegalStateException
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public String indexState(int includedOptions)
-			throws IllegalStateException, IOException {
+			throws IOException {
 		return indexState(db, includedOptions);
 	}
 
@@ -251,7 +266,9 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 *            a {@link org.eclipse.jgit.treewalk.FileTreeIterator} which
 	 *            determines which files should go into the new index
 	 * @throws FileNotFoundException
+	 *             file was not found
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected void resetIndex(FileTreeIterator treeItr)
 			throws FileNotFoundException, IOException {
@@ -339,7 +356,9 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * @return return the last measured value of the filesystem timer which is
 	 *         greater than then the lastmodification time of lastfile.
 	 * @throws InterruptedException
+	 *             if thread was interrupted
 	 * @throws IOException
+	 *             if an IO error occurred
 	 * @since 5.1.9
 	 */
 	public static Instant fsTick(File lastFile)
@@ -378,8 +397,11 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Create a branch
 	 *
 	 * @param objectId
+	 *            new value to create the branch on
 	 * @param branchName
+	 *            branch name
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected void createBranch(ObjectId objectId, String branchName)
 			throws IOException {
@@ -393,6 +415,7 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 *
 	 * @return list of refs
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public List<Ref> getRefs() throws IOException {
 		return db.getRefDatabase().getRefs();
@@ -402,11 +425,12 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Checkout a branch
 	 *
 	 * @param branchName
-	 * @throws IllegalStateException
+	 *            branch name
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected void checkoutBranch(String branchName)
-			throws IllegalStateException, IOException {
+			throws IOException {
 		try (RevWalk walk = new RevWalk(db)) {
 			RevCommit head = walk.parseCommit(db.resolve(Constants.HEAD));
 			RevCommit branch = walk.parseCommit(db.resolve(branchName));
@@ -436,7 +460,9 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 *            the contents which should be written into the files
 	 * @return the File object associated to the last written file.
 	 * @throws IOException
+	 *             if an IO error occurred
 	 * @throws InterruptedException
+	 *             if thread was interrupted
 	 */
 	protected File writeTrashFiles(boolean ensureDistinctTimestamps,
 			String... contents)
@@ -459,8 +485,11 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * one.
 	 *
 	 * @param filename
+	 *            file name
 	 * @param contents
+	 *            file content
 	 * @param branch
+	 *            branch name
 	 * @return the created commit
 	 */
 	protected RevCommit commitFile(String filename, String contents, String branch) {
@@ -494,7 +523,9 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Create <code>DirCacheEntry</code>
 	 *
 	 * @param path
+	 *            file path
 	 * @param mode
+	 *            file mode
 	 * @return the DirCacheEntry
 	 */
 	protected DirCacheEntry createEntry(String path, FileMode mode) {
@@ -505,8 +536,11 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Create <code>DirCacheEntry</code>
 	 *
 	 * @param path
+	 *            file path
 	 * @param mode
+	 *            file mode
 	 * @param content
+	 *            file content
 	 * @return the DirCacheEntry
 	 */
 	protected DirCacheEntry createEntry(final String path, final FileMode mode,
@@ -518,9 +552,13 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Create <code>DirCacheEntry</code>
 	 *
 	 * @param path
+	 *            file path
 	 * @param mode
+	 *            file mode
 	 * @param stage
+	 *            stage index of the new entry
 	 * @param content
+	 *            file content
 	 * @return the DirCacheEntry
 	 */
 	protected DirCacheEntry createEntry(final String path, final FileMode mode,
@@ -538,7 +576,9 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Create <code>DirCacheEntry</code>
 	 *
 	 * @param path
+	 *            file path
 	 * @param objectId
+	 *            of the entry
 	 * @return the DirCacheEntry
 	 */
 	protected DirCacheEntry createGitLink(String path, AnyObjectId objectId) {
@@ -553,8 +593,11 @@ public abstract class RepositoryTestCase extends LocalDiskRepositoryTestCase {
 	 * Assert files are equal
 	 *
 	 * @param expected
+	 *            expected file
 	 * @param actual
+	 *            actual file
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static void assertEqualsFile(File expected, File actual)
 			throws IOException {
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/StrictWorkMonitor.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/StrictWorkMonitor.java
index c77bca9751..0168ecea30 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/StrictWorkMonitor.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/StrictWorkMonitor.java
@@ -20,32 +20,27 @@ import org.eclipse.jgit.lib.ProgressMonitor;
 public final class StrictWorkMonitor implements ProgressMonitor {
 	private int lastWork, totalWork;
 
-	/** {@inheritDoc} */
 	@Override
 	public void start(int totalTasks) {
 		// empty
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void beginTask(String title, int total) {
 		this.totalWork = total;
 		lastWork = 0;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void update(int completed) {
 		lastWork += completed;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void endTask() {
 		assertEquals("Units of work recorded", totalWork, lastWork);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public boolean isCancelled() {
 		return false;
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/TestRepository.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/TestRepository.java
index 483b9a7c81..4b45535477 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/TestRepository.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/TestRepository.java
@@ -115,6 +115,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 * @param db
 	 *            the test repository to write into.
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public TestRepository(R db) throws IOException {
 		this(db, new RevWalk(db), new MockSystemReader());
@@ -128,6 +129,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 * @param rw
 	 *            the RevObject pool to use for object lookup.
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public TestRepository(R db, RevWalk rw) throws IOException {
 		this(db, rw, new MockSystemReader());
@@ -144,6 +146,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            the MockSystemReader to use for clock and other system
 	 *            operations.
 	 * @throws IOException
+	 *             if an IO error occurred
 	 * @since 4.2
 	 */
 	public TestRepository(R db, RevWalk rw, MockSystemReader reader)
@@ -235,6 +238,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            file content, will be UTF-8 encoded.
 	 * @return reference to the blob.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevBlob blob(String content) throws Exception {
 		return blob(content.getBytes(UTF_8));
@@ -247,6 +251,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            binary file content.
 	 * @return the new, fully parsed blob.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevBlob blob(byte[] content) throws Exception {
 		ObjectId id;
@@ -266,6 +271,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            a blob, previously constructed in the repository.
 	 * @return the entry.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public DirCacheEntry file(String path, RevBlob blob)
 			throws Exception {
@@ -284,6 +290,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            a blob, previously constructed in the repository.
 	 * @return the entry.
 	 * @throws Exception
+	 *             if an error occurred
 	 * @since 6.3
 	 */
 	public DirCacheEntry link(String path, RevBlob blob) throws Exception {
@@ -301,6 +308,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            to be sorted properly and may be empty.
 	 * @return the new, fully parsed tree specified by the entry list.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevTree tree(DirCacheEntry... entries) throws Exception {
 		final DirCache dc = DirCache.newInCore();
@@ -326,6 +334,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            the path to find the entry of.
 	 * @return the parsed object entry at this path, never null.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevObject get(RevTree tree, String path)
 			throws Exception {
@@ -357,6 +366,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            zero or more IDs of the commit's parents.
 	 * @return the ID of the new commit.
 	 * @throws Exception
+	 *             if an error occurred
 	 * @since 5.5
 	 */
 	public ObjectId unparsedCommit(ObjectId... parents) throws Exception {
@@ -373,6 +383,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            zero or more parents of the commit.
 	 * @return the new commit.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevCommit commit(RevCommit... parents) throws Exception {
 		return commit(1, tree(), parents);
@@ -389,6 +400,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            zero or more parents of the commit.
 	 * @return the new commit.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevCommit commit(RevTree tree, RevCommit... parents)
 			throws Exception {
@@ -407,6 +419,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            zero or more parents of the commit.
 	 * @return the new commit.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevCommit commit(int secDelta, RevCommit... parents)
 			throws Exception {
@@ -428,6 +441,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            zero or more parents of the commit.
 	 * @return the new, fully parsed commit.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevCommit commit(final int secDelta, final RevTree tree,
 			final RevCommit... parents) throws Exception {
@@ -450,6 +464,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            zero or more IDs of the commit's parents.
 	 * @return the ID of the new commit.
 	 * @throws Exception
+	 *             if an error occurred
 	 * @since 5.5
 	 */
 	public ObjectId unparsedCommit(final int secDelta, final RevTree tree,
@@ -496,6 +511,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            object the tag should be pointed at.
 	 * @return the new, fully parsed annotated tag object.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevTag tag(String name, RevObject dst) throws Exception {
 		final TagBuilder t = new TagBuilder();
@@ -524,6 +540,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            the target object.
 	 * @return the target object.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevCommit update(String ref, CommitBuilder to) throws Exception {
 		return update(ref, to.create());
@@ -534,12 +551,13 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *
 	 * @param ref
 	 *            the name of the reference to amend, which must already exist.
-	 *            If {@code ref} does not start with {@code refs/} and is not the
-	 *            magic names {@code HEAD} {@code FETCH_HEAD} or {@code
-	 *            MERGE_HEAD}, then {@code refs/heads/} will be prefixed in front
-	 *            of the given name, thereby assuming it is a branch.
+	 *            If {@code ref} does not start with {@code refs/} and is not
+	 *            the magic names {@code HEAD} {@code FETCH_HEAD} or {@code
+	 *            MERGE_HEAD}, then {@code refs/heads/} will be prefixed in
+	 *            front of the given name, thereby assuming it is a branch.
 	 * @return commit builder that amends the branch on commit.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public CommitBuilder amendRef(String ref) throws Exception {
 		String name = normalizeRef(ref);
@@ -556,6 +574,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            the id of the commit to amend.
 	 * @return commit builder.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public CommitBuilder amend(AnyObjectId id) throws Exception {
 		return amend(pool.parseCommit(id), commit());
@@ -610,6 +629,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            the target object.
 	 * @return the target object.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public <T extends AnyObjectId> T update(String ref, T obj) throws Exception {
 		ref = normalizeRef(ref);
@@ -632,9 +652,10 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 * Delete a reference.
 	 *
 	 * @param ref
-	 *	      the name of the reference to delete. This is normalized
-	 *	      in the same way as {@link #update(String, AnyObjectId)}.
+	 *            the name of the reference to delete. This is normalized in the
+	 *            same way as {@link #update(String, AnyObjectId)}.
 	 * @throws Exception
+	 *             if an error occurred
 	 * @since 4.4
 	 */
 	public void delete(String ref) throws Exception {
@@ -674,6 +695,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 * @param id
 	 *            ID of detached head.
 	 * @throws Exception
+	 *             if an error occurred
 	 * @see #reset(String)
 	 */
 	public void reset(AnyObjectId id) throws Exception {
@@ -695,13 +717,14 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	/**
 	 * Soft-reset HEAD to a different commit.
 	 * <p>
-	 * This is equivalent to {@code git reset --soft} in that it modifies HEAD but
-	 * not the index or the working tree of a non-bare repository.
+	 * This is equivalent to {@code git reset --soft} in that it modifies HEAD
+	 * but not the index or the working tree of a non-bare repository.
 	 *
 	 * @param name
-	 *            revision string; either an existing ref name, or something that
-	 *            can be parsed to an object ID.
+	 *            revision string; either an existing ref name, or something
+	 *            that can be parsed to an object ID.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public void reset(String name) throws Exception {
 		RefUpdate.Result result;
@@ -735,6 +758,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 * @return the new, fully parsed commit, or null if no work was done due to
 	 *         the resulting tree being identical.
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public RevCommit cherryPick(AnyObjectId id) throws Exception {
 		RevCommit commit = pool.parseCommit(id);
@@ -779,6 +803,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 * Update the dumb client server info files.
 	 *
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public void updateServerInfo() throws Exception {
 		if (db instanceof FileRepository) {
@@ -816,6 +841,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            parsing of.
 	 * @return {@code object}
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public <T extends RevObject> T parseBody(T object) throws Exception {
 		pool.parseBody(object);
@@ -851,6 +877,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            the object to tag
 	 * @return the tagged object
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public ObjectId lightweightTag(String name, ObjectId obj) throws Exception {
 		if (!name.startsWith(Constants.R_TAGS))
@@ -868,8 +895,11 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 *            the tips to start checking from; if not supplied the refs of
 	 *            the repository are used instead.
 	 * @throws MissingObjectException
+	 *             if object is missing
 	 * @throws IncorrectObjectTypeException
+	 *             if object has unexpected type
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public void fsck(RevObject... tips) throws MissingObjectException,
 			IncorrectObjectTypeException, IOException {
@@ -922,6 +952,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 	 * not removed.
 	 *
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public void packAndPrune() throws Exception {
 		if (db.getObjectDatabase() instanceof ObjectDirectory) {
@@ -1022,6 +1053,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 		 *            the commit to update to.
 		 * @return {@code to}.
 		 * @throws Exception
+		 *             if an error occurred
 		 */
 		public RevCommit update(CommitBuilder to) throws Exception {
 			return update(to.create());
@@ -1034,6 +1066,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 		 *            the commit to update to.
 		 * @return {@code to}.
 		 * @throws Exception
+		 *             if an error occurred
 		 */
 		public RevCommit update(RevCommit to) throws Exception {
 			return TestRepository.this.update(ref, to);
@@ -1041,7 +1074,9 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 
 		/**
 		 * Delete this branch.
+		 *
 		 * @throws Exception
+		 *             if an error occurred
 		 * @since 4.4
 		 */
 		public void delete() throws Exception {
@@ -1102,6 +1137,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 		 *            parent commit
 		 * @return this commit builder
 		 * @throws Exception
+		 *             if an error occurred
 		 */
 		public CommitBuilder parent(RevCommit p) throws Exception {
 			if (parents.isEmpty()) {
@@ -1165,6 +1201,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 		 *            the file content
 		 * @return this commit builder
 		 * @throws Exception
+		 *             if an error occurred
 		 */
 		public CommitBuilder add(String path, String content) throws Exception {
 			return add(path, blob(content));
@@ -1179,6 +1216,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 		 *            blob for this file
 		 * @return this commit builder
 		 * @throws Exception
+		 *             if an error occurred
 		 */
 		public CommitBuilder add(String path, RevBlob id)
 				throws Exception {
@@ -1404,6 +1442,7 @@ public class TestRepository<R extends Repository> implements AutoCloseable {
 		 *
 		 * @return child commit builder
 		 * @throws Exception
+		 *             if an error occurred
 		 */
 		public CommitBuilder child() throws Exception {
 			return new CommitBuilder(this);
diff --git a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/time/MonotonicFakeClock.java b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/time/MonotonicFakeClock.java
index e5338d36cd..31db6a2c7b 100644
--- a/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/time/MonotonicFakeClock.java
+++ b/org.eclipse.jgit.junit/src/org/eclipse/jgit/junit/time/MonotonicFakeClock.java
@@ -40,7 +40,6 @@ public class MonotonicFakeClock implements MonotonicClock {
 		now += unit.toMillis(add);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public ProposedTimestamp propose() {
 		long t = now++;