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>

7 files changed, 35 insertions, 8 deletions

diff --git a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AccessEvent.java b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AccessEvent.java
index 873d430675..3d4f379243 100644
--- a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AccessEvent.java
+++ b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AccessEvent.java
@@ -146,7 +146,6 @@ public class AccessEvent {
 		return responseHeaders != null ? responseHeaders.get(name) : null;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String toString() {
 		StringBuilder b = new StringBuilder();
diff --git a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AppServer.java b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AppServer.java
index 36f2f2bc7f..de4535ab52 100644
--- a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AppServer.java
+++ b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/AppServer.java
@@ -260,7 +260,9 @@ public class AppServer {
 	 * Configure basic authentication.
 	 *
 	 * @param ctx
+	 *            servlet context handler
 	 * @param methods
+	 *            the methods
 	 * @return servlet context handler
 	 */
 	public ServletContextHandler authBasic(ServletContextHandler ctx,
diff --git a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/HttpTestCase.java b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/HttpTestCase.java
index 877b918695..8a4d363709 100644
--- a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/HttpTestCase.java
+++ b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/HttpTestCase.java
@@ -45,14 +45,12 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	/** In-memory application server; subclass must start. */
 	protected AppServer server;
 
-	/** {@inheritDoc} */
 	@Override
 	public void setUp() throws Exception {
 		super.setUp();
 		server = createServer();
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void tearDown() throws Exception {
 		server.tearDown();
@@ -78,6 +76,7 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 *
 	 * @return the TestRepository
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected TestRepository<Repository> createTestRepository()
 			throws IOException {
@@ -90,8 +89,10 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Convert path to URIish
 	 *
 	 * @param path
+	 *            the path
 	 * @return the URIish
 	 * @throws URISyntaxException
+	 *             if URI is invalid
 	 */
 	protected URIish toURIish(String path) throws URISyntaxException {
 		URI u = server.getURI().resolve(path);
@@ -102,9 +103,12 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Convert a path relative to the app's context path to a URIish
 	 *
 	 * @param app
+	 *            app name
 	 * @param name
+	 *            context path name
 	 * @return the warnings (if any) from the last execution
 	 * @throws URISyntaxException
+	 *             if URI is invalid
 	 */
 	protected URIish toURIish(ServletContextHandler app, String name)
 			throws URISyntaxException {
@@ -128,7 +132,9 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Get requests.
 	 *
 	 * @param base
+	 *            base URI
 	 * @param path
+	 *            the request path relative to {@code base}
 	 *
 	 * @return list of events
 	 */
@@ -140,6 +146,7 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Get requests.
 	 *
 	 * @param path
+	 *            request path
 	 *
 	 * @return list of events
 	 */
@@ -151,8 +158,11 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Run fsck
 	 *
 	 * @param db
+	 *            the repository
 	 * @param tips
+	 *            tips to start checking from
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	protected static void fsck(Repository db, RevObject... tips)
 			throws Exception {
@@ -166,6 +176,7 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Mirror refs
 	 *
 	 * @param refs
+	 *            the refs
 	 * @return set of RefSpecs
 	 */
 	protected static Set<RefSpec> mirror(String... refs) {
@@ -183,9 +194,12 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Push a commit
 	 *
 	 * @param from
+	 *            repository from which to push
 	 * @param q
+	 *            commit to push
 	 * @return collection of RefUpdates
 	 * @throws IOException
+	 *             if an IO error occurred
 	 */
 	protected static Collection<RemoteRefUpdate> push(TestRepository from,
 			RevCommit q) throws IOException {
@@ -205,7 +219,9 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Create loose object path
 	 *
 	 * @param base
+	 *            base URI
 	 * @param id
+	 *            objectId
 	 * @return path of the loose object
 	 */
 	public static String loose(URIish base, AnyObjectId id) {
@@ -219,6 +235,7 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Join a base URIish and a path
 	 *
 	 * @param base
+	 *            base URI
 	 * @param path
 	 *            a relative path
 	 * @return the joined path
@@ -237,8 +254,11 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Rewrite a url
 	 *
 	 * @param url
+	 *            the URL
 	 * @param newProtocol
+	 *            new protocol
 	 * @param newPort
+	 *            new port
 	 * @return the rewritten url
 	 */
 	protected static String rewriteUrl(String url, String newProtocol,
@@ -263,9 +283,12 @@ public abstract class HttpTestCase extends LocalDiskRepositoryTestCase {
 	 * Extend a path
 	 *
 	 * @param uri
+	 *            the URI
 	 * @param pathComponents
+	 *            path components
 	 * @return the extended URIish
 	 * @throws URISyntaxException
+	 *             if URI is invalid
 	 */
 	protected static URIish extendPath(URIish uri, String pathComponents)
 			throws URISyntaxException {
diff --git a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/MockServletConfig.java b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/MockServletConfig.java
index 715fd19451..cd1eba4bfd 100644
--- a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/MockServletConfig.java
+++ b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/MockServletConfig.java
@@ -28,19 +28,19 @@ public class MockServletConfig implements ServletConfig {
 	 * Set init parameter.
 	 *
 	 * @param name
+	 *            parameter name
 	 * @param value
+	 *            parameter value
 	 */
 	public void setInitParameter(String name, String value) {
 		parameters.put(name, value);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getInitParameter(String name) {
 		return parameters.get(name);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public Enumeration<String> getInitParameterNames() {
 		final Iterator<String> i = parameters.keySet().iterator();
@@ -58,13 +58,11 @@ public class MockServletConfig implements ServletConfig {
 		};
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getServletName() {
 		return "MOCK_SERVLET";
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public ServletContext getServletContext() {
 		return null;
diff --git a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/RecordingLogger.java b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/RecordingLogger.java
index af63084e93..f56e1fa5c4 100644
--- a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/RecordingLogger.java
+++ b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/RecordingLogger.java
@@ -70,6 +70,7 @@ public class RecordingLogger extends MarkerIgnoringBase {
 	 * Constructor for <code>RecordingLogger</code>.
 	 *
 	 * @param name
+	 *            logger name
 	 */
 	public RecordingLogger(String name) {
 		this.name = name;
diff --git a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/SimpleHttpServer.java b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/SimpleHttpServer.java
index 2493f999fa..01f18dab75 100644
--- a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/SimpleHttpServer.java
+++ b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/SimpleHttpServer.java
@@ -40,6 +40,7 @@ public class SimpleHttpServer {
 	 * Constructor for <code>SimpleHttpServer</code>.
 	 *
 	 * @param repository
+	 *            the repository
 	 */
 	public SimpleHttpServer(Repository repository) {
 		this(repository, false);
@@ -49,7 +50,9 @@ public class SimpleHttpServer {
 	 * Constructor for <code>SimpleHttpServer</code>.
 	 *
 	 * @param repository
+	 *            the repository
 	 * @param withSsl
+	 *            whether to encrypt the communication
 	 */
 	public SimpleHttpServer(Repository repository, boolean withSsl) {
 		this.db = repository;
@@ -60,6 +63,7 @@ public class SimpleHttpServer {
 	 * Start the server
 	 *
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public void start() throws Exception {
 		ServletContextHandler sBasic = server.authBasic(smart("/sbasic"));
@@ -76,6 +80,7 @@ public class SimpleHttpServer {
 	 * Stop the server.
 	 *
 	 * @throws Exception
+	 *             if an error occurred
 	 */
 	public void stop() throws Exception {
 		server.tearDown();
diff --git a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/TestRequestLog.java b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/TestRequestLog.java
index 04cb2428a2..afa8c35bb2 100644
--- a/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/TestRequestLog.java
+++ b/org.eclipse.jgit.junit.http/src/org/eclipse/jgit/junit/http/TestRequestLog.java
@@ -72,7 +72,6 @@ class TestRequestLog extends HandlerWrapper {
 		}
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void handle(String target, Request baseRequest,
 			HttpServletRequest request, HttpServletResponse response)