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>

11 files changed, 12 insertions, 18 deletions

diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/CleanFilter.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/CleanFilter.java
index f0526ff8a2..13b74dff7d 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/CleanFilter.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/CleanFilter.java
@@ -95,7 +95,6 @@ public class CleanFilter extends FilterCommand {
 		this.aOut = new AtomicObjectOutputStream(tmpFile.toAbsolutePath());
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public int run() throws IOException {
 		try {
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/LfsPointer.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/LfsPointer.java
index 0a8a3faec3..afe963640d 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/LfsPointer.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/LfsPointer.java
@@ -136,6 +136,7 @@ public class LfsPointer implements Comparable<LfsPointer> {
 	 * @return an {@link org.eclipse.jgit.lfs.LfsPointer} or {@code null} if the
 	 *         stream was not parseable as LfsPointer
 	 * @throws java.io.IOException
+	 *             if an IO error occurred
 	 */
 	@Nullable
 	public static LfsPointer parseLfsPointer(InputStream in)
@@ -264,7 +265,6 @@ public class LfsPointer implements Comparable<LfsPointer> {
 		return VERSION.equals(rest) || VERSION_LEGACY.equals(rest);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		return "LfsPointer: oid=" + oid.name() + ", size=" //$NON-NLS-1$ //$NON-NLS-2$
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/SmudgeFilter.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/SmudgeFilter.java
index c26a1bfbb3..b6515b92e1 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/SmudgeFilter.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/SmudgeFilter.java
@@ -127,6 +127,7 @@ public class SmudgeFilter extends FilterCommand {
 	 *            the objects to download
 	 * @return the paths of all mediafiles which have been downloaded
 	 * @throws IOException
+	 *             if an IO error occurred
 	 * @since 4.11
 	 */
 	public static Collection<Path> downloadLfsResource(Lfs lfs, Repository db,
@@ -217,7 +218,6 @@ public class SmudgeFilter extends FilterCommand {
 		return downloadedPaths;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public int run() throws IOException {
 		try {
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/AtomicObjectOutputStream.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/AtomicObjectOutputStream.java
index 3f1f0acac4..009250294e 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/AtomicObjectOutputStream.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/AtomicObjectOutputStream.java
@@ -45,6 +45,7 @@ public class AtomicObjectOutputStream extends OutputStream {
 	 * @param id
 	 *            a {@link org.eclipse.jgit.lfs.lib.AnyLongObjectId} object.
 	 * @throws java.io.IOException
+	 *             if an IO error occurred
 	 */
 	public AtomicObjectOutputStream(Path path, AnyLongObjectId id)
 			throws IOException {
@@ -61,6 +62,7 @@ public class AtomicObjectOutputStream extends OutputStream {
 	 * @param path
 	 *            a {@link java.nio.file.Path} object.
 	 * @throws java.io.IOException
+	 *             if an IO error occurred
 	 */
 	public AtomicObjectOutputStream(Path path) throws IOException {
 		this(path, null);
@@ -78,25 +80,21 @@ public class AtomicObjectOutputStream extends OutputStream {
 		return id;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void write(int b) throws IOException {
 		out.write(b);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void write(byte[] b) throws IOException {
 		out.write(b);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void write(byte[] b, int off, int len) throws IOException {
 		out.write(b, off, len);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void close() throws IOException {
 		out.close();
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConfig.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConfig.java
index 857ccbe056..0469337b1f 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConfig.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConfig.java
@@ -70,6 +70,7 @@ public class LfsConfig {
 	 *
 	 * @return the delegate {@link Config}
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	private Config getDelegate() throws IOException {
 		if (delegate == null) {
@@ -86,6 +87,7 @@ public class LfsConfig {
 	 * @return The loaded lfs config
 	 *
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	private Config load() throws IOException {
 		Config result = null;
@@ -114,6 +116,7 @@ public class LfsConfig {
 	 *
 	 * @return the config, or <code>null</code>
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	@Nullable
 	private Config loadFromWorkingTree()
@@ -139,6 +142,7 @@ public class LfsConfig {
 	 *
 	 * @return the config, or <code>null</code> if the entry does not exist
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	@Nullable
 	private Config loadFromIndex()
@@ -162,6 +166,7 @@ public class LfsConfig {
 	 *
 	 * @return the config, or <code>null</code> if the file does not exist
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	@Nullable
 	private Config loadFromHead() throws IOException {
@@ -207,6 +212,7 @@ public class LfsConfig {
 	 *            the key name
 	 * @return a String value from the config, <code>null</code> if not found
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	@Nullable
 	public String getString(final String section, final String subsection,
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConnectionFactory.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConnectionFactory.java
index 12b688d157..f9c623d8b7 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConnectionFactory.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/internal/LfsConnectionFactory.java
@@ -67,6 +67,7 @@ public class LfsConnectionFactory {
 	 * @return the connection for the lfs server. e.g.
 	 *         "https://github.com/github/git-lfs.git/info/lfs"
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	public static HttpConnection getLfsConnection(Repository db, String method,
 			String purpose) throws IOException {
@@ -287,6 +288,7 @@ public class LfsConnectionFactory {
 		 * no timeout can be determined, the token will be used only once.
 		 *
 		 * @param action
+		 *            action with an additional expiration timestamp
 		 */
 		public AuthCache(Protocol.ExpiringAction action) {
 			this.cachedAction = action;
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AbbreviatedLongObjectId.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AbbreviatedLongObjectId.java
index 9016e53940..7ae805c33f 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AbbreviatedLongObjectId.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AbbreviatedLongObjectId.java
@@ -314,13 +314,11 @@ public final class AbbreviatedLongObjectId implements Serializable {
 		return mask(nibbles, word, v);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public int hashCode() {
 		return (int) (w1 >> 32);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public boolean equals(Object o) {
 		if (o instanceof AbbreviatedLongObjectId) {
@@ -355,7 +353,6 @@ public final class AbbreviatedLongObjectId implements Serializable {
 		return new String(b, 0, nibbles);
 	}
 
-	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AnyLongObjectId.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AnyLongObjectId.java
index d866db4a2d..75d500ef20 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AnyLongObjectId.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/AnyLongObjectId.java
@@ -249,7 +249,6 @@ public abstract class AnyLongObjectId implements Comparable<AnyLongObjectId> {
 		return abbr.prefixCompare(this) == 0;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public final int hashCode() {
 		return (int) (w1 >> 32);
@@ -267,7 +266,6 @@ public abstract class AnyLongObjectId implements Comparable<AnyLongObjectId> {
 		return other != null ? equals(this, other) : false;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public final boolean equals(Object o) {
 		if (o instanceof AnyLongObjectId) {
@@ -475,7 +473,6 @@ public abstract class AnyLongObjectId implements Comparable<AnyLongObjectId> {
 			dst[o--] = '0';
 	}
 
-	/** {@inheritDoc} */
 	@SuppressWarnings("nls")
 	@Override
 	public String toString() {
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LfsPointerFilter.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LfsPointerFilter.java
index 99bae49abb..75798ca0f1 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LfsPointerFilter.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LfsPointerFilter.java
@@ -41,7 +41,6 @@ public class LfsPointerFilter extends TreeFilter {
 		return pointer;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public boolean include(TreeWalk walk) throws MissingObjectException,
 			IncorrectObjectTypeException, IOException {
@@ -63,13 +62,11 @@ public class LfsPointerFilter extends TreeFilter {
 		}
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public boolean shouldBeRecursive() {
 		return false;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public TreeFilter clone() {
 		return new LfsPointerFilter();
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LongObjectId.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LongObjectId.java
index 15b3ca4c62..3959115462 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LongObjectId.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/LongObjectId.java
@@ -256,7 +256,6 @@ public class LongObjectId extends AnyLongObjectId implements Serializable {
 		w4 = src.w4;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public LongObjectId toObjectId() {
 		return this;
diff --git a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/MutableLongObjectId.java b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/MutableLongObjectId.java
index 012e4ae915..5397d8135c 100644
--- a/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/MutableLongObjectId.java
+++ b/org.eclipse.jgit.lfs/src/org/eclipse/jgit/lfs/lib/MutableLongObjectId.java
@@ -221,7 +221,6 @@ public class MutableLongObjectId extends AnyLongObjectId {
 		}
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public LongObjectId toObjectId() {
 		return new LongObjectId(this);