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>

3 files changed, 13 insertions, 29 deletions

diff --git a/org.eclipse.jgit.http.apache/.settings/org.eclipse.jdt.core.prefs b/org.eclipse.jgit.http.apache/.settings/org.eclipse.jdt.core.prefs
index f79df5b9dd..a08ba7b56f 100644
--- a/org.eclipse.jgit.http.apache/.settings/org.eclipse.jdt.core.prefs
+++ b/org.eclipse.jgit.http.apache/.settings/org.eclipse.jdt.core.prefs
@@ -52,7 +52,7 @@ org.eclipse.jdt.core.compiler.problem.missingHashCodeMethod=error
 org.eclipse.jdt.core.compiler.problem.missingJavadocComments=error
 org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsOverriding=disabled
 org.eclipse.jdt.core.compiler.problem.missingJavadocCommentsVisibility=protected
-org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=return_tag
+org.eclipse.jdt.core.compiler.problem.missingJavadocTagDescription=all_standard_tags
 org.eclipse.jdt.core.compiler.problem.missingJavadocTags=error
 org.eclipse.jdt.core.compiler.problem.missingJavadocTagsMethodTypeParameters=disabled
 org.eclipse.jdt.core.compiler.problem.missingJavadocTagsOverriding=disabled
diff --git a/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/HttpClientConnection.java b/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/HttpClientConnection.java
index 90348f54b9..6d806dee37 100644
--- a/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/HttpClientConnection.java
+++ b/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/HttpClientConnection.java
@@ -203,6 +203,7 @@ public class HttpClientConnection implements HttpConnection {
 	 * Sets the buffer from which to take the request body
 	 *
 	 * @param buffer
+	 *            the buffer
 	 */
 	public void setBuffer(TemporaryBuffer buffer) {
 		this.entity = new TemporaryBufferEntity(buffer);
@@ -212,7 +213,9 @@ public class HttpClientConnection implements HttpConnection {
 	 * Constructor for HttpClientConnection.
 	 *
 	 * @param urlStr
+	 *            url string
 	 * @throws MalformedURLException
+	 *             if url is malformed
 	 */
 	public HttpClientConnection(String urlStr) throws MalformedURLException {
 		this(urlStr, null);
@@ -222,8 +225,11 @@ public class HttpClientConnection implements HttpConnection {
 	 * Constructor for HttpClientConnection.
 	 *
 	 * @param urlStr
+	 *            url string
 	 * @param proxy
+	 *            proxy
 	 * @throws MalformedURLException
+	 *             if url is malformed
 	 */
 	public HttpClientConnection(String urlStr, Proxy proxy)
 			throws MalformedURLException {
@@ -234,9 +240,13 @@ public class HttpClientConnection implements HttpConnection {
 	 * Constructor for HttpClientConnection.
 	 *
 	 * @param urlStr
+	 *            url string
 	 * @param proxy
+	 *            proxy
 	 * @param cl
+	 *            client
 	 * @throws MalformedURLException
+	 *             if url is malformed
 	 */
 	public HttpClientConnection(String urlStr, Proxy proxy, HttpClient cl)
 			throws MalformedURLException {
@@ -245,20 +255,17 @@ public class HttpClientConnection implements HttpConnection {
 		this.proxy = proxy;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public int getResponseCode() throws IOException {
 		execute();
 		return resp.getStatusLine().getStatusCode();
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public URL getURL() {
 		return url;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getResponseMessage() throws IOException {
 		execute();
@@ -287,7 +294,6 @@ public class HttpClientConnection implements HttpConnection {
 		}
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public Map<String, List<String>> getHeaderFields() {
 		Map<String, List<String>> ret = new HashMap<>();
@@ -304,13 +310,11 @@ public class HttpClientConnection implements HttpConnection {
 		return ret;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setRequestProperty(String name, String value) {
 		req.addHeader(name, value);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setRequestMethod(String method) throws ProtocolException {
 		this.method = method;
@@ -328,25 +332,21 @@ public class HttpClientConnection implements HttpConnection {
 		}
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setUseCaches(boolean usecaches) {
 		// not needed
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setConnectTimeout(int timeout) {
 		this.timeout = Integer.valueOf(timeout);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setReadTimeout(int readTimeout) {
 		this.readTimeout = Integer.valueOf(readTimeout);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getContentType() {
 		HttpEntity responseEntity = resp.getEntity();
@@ -358,7 +358,6 @@ public class HttpClientConnection implements HttpConnection {
 		return null;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public InputStream getInputStream() throws IOException {
 		execute();
@@ -366,7 +365,6 @@ public class HttpClientConnection implements HttpConnection {
 	}
 
 	// will return only the first field
-	/** {@inheritDoc} */
 	@Override
 	public String getHeaderField(@NonNull String name) {
 		Header header = resp.getFirstHeader(name);
@@ -379,7 +377,6 @@ public class HttpClientConnection implements HttpConnection {
 				.stream().map(Header::getValue).collect(Collectors.toList()));
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public int getContentLength() {
 		Header contentLength = resp.getFirstHeader("content-length"); //$NON-NLS-1$
@@ -395,19 +392,16 @@ public class HttpClientConnection implements HttpConnection {
 		}
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setInstanceFollowRedirects(boolean followRedirects) {
 		this.followRedirects = Boolean.valueOf(followRedirects);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setDoOutput(boolean dooutput) {
 		// TODO: check whether we can really ignore this.
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setFixedLengthStreamingMode(int contentLength) {
 		if (entity != null)
@@ -416,7 +410,6 @@ public class HttpClientConnection implements HttpConnection {
 		entity.setContentLength(contentLength);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public OutputStream getOutputStream() throws IOException {
 		if (entity == null)
@@ -424,7 +417,6 @@ public class HttpClientConnection implements HttpConnection {
 		return entity.getBuffer();
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setChunkedStreamingMode(int chunklen) {
 		if (entity == null)
@@ -432,31 +424,26 @@ public class HttpClientConnection implements HttpConnection {
 		entity.setChunked(true);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public String getRequestMethod() {
 		return method;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public boolean usingProxy() {
 		return isUsingProxy;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void connect() throws IOException {
 		execute();
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void setHostnameVerifier(HostnameVerifier hostnameverifier) {
 		this.hostnameverifier = hostnameverifier;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void configure(KeyManager[] km, TrustManager[] tm,
 			SecureRandom random) throws KeyManagementException {
diff --git a/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/TemporaryBufferEntity.java b/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/TemporaryBufferEntity.java
index 101886c887..40be0747ef 100644
--- a/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/TemporaryBufferEntity.java
+++ b/org.eclipse.jgit.http.apache/src/org/eclipse/jgit/transport/http/apache/TemporaryBufferEntity.java
@@ -33,6 +33,7 @@ public class TemporaryBufferEntity extends AbstractHttpEntity
 	 * content stored in the specified buffer
 	 *
 	 * @param buffer
+	 *            the buffer
 	 */
 	public TemporaryBufferEntity(TemporaryBuffer buffer) {
 		this.buffer = buffer;
@@ -47,13 +48,11 @@ public class TemporaryBufferEntity extends AbstractHttpEntity
 		return buffer;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public boolean isRepeatable() {
 		return true;
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public long getContentLength() {
 		if (contentLength != null)
@@ -61,20 +60,17 @@ public class TemporaryBufferEntity extends AbstractHttpEntity
 		return buffer.length();
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public InputStream getContent() throws IOException, IllegalStateException {
 		return buffer.openInputStream();
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public void writeTo(OutputStream outstream) throws IOException {
 		// TODO: dont we need a progressmonitor
 		buffer.writeTo(outstream, null);
 	}
 
-	/** {@inheritDoc} */
 	@Override
 	public boolean isStreaming() {
 		return false;
@@ -84,6 +80,7 @@ public class TemporaryBufferEntity extends AbstractHttpEntity
 	 * Set the <code>contentLength</code>
 	 *
 	 * @param contentLength
+	 *            content length
 	 */
 	public void setContentLength(int contentLength) {
 		this.contentLength = Integer.valueOf(contentLength);