OSGi can have its plugin localization at an arbitrary place; there is
no need to have it in a top-level plugin.properties file. In non-OSGi
environments having the files at the root level may mean that these
files clash with each other, or, as in the referenced bug, with some
third-party plug-in's plugin.properties, which may not even have
anything to do with localization.
Move our OSGi localization to a subfolder OSGI-INF/l10n. For OSGi
environments, that's just as good, and for non-OSGi environments it
avoid clashes with other root level items on the classpath or in a fat
JAR.
For fragments, use neither plugin.properties (which would clash with the
host plug-in's plugin.properties) nor fragment.properties (which might
clash with other fragments for the same fragment host bundle). Instead
use names "relative" to the host bundle.
Bug: 582394
Change-Id: Ifbcd046d912e2cfe86c0f7259c5ca8de599d9aa1
Signed-off-by: Thomas Wolf <twolf@apache.org>
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 (`< and `>`).
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>
Add the missing Bundle-Localization header.
Bug: 580081
Change-Id: If21e0778dbb60b49a8f83030461670656eeb0ce4
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
Errorprone raises the following warning: "[ReferenceEquality] Comparison
using reference equality instead of value equality".
Change-Id: Ic73305b2af628f66e7659ea1b839b3a640e3cd8d
Explain SSH agent protocols, what transports are available and how to
choose them in ~/.ssh/config. For Windows, add some information on
which commonly used SSH agents can be used.
Change-Id: I0b08a95654fd76643512606edb1ed74d9980aa85
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
OpenSSH has (for legacy reasons?) the option of specifying the default
environment variable directly, instead of using ${SSH_AUTH_SOCK}. Make
sure the plain variable name is not taken as a relative path name.
Bug: 577053
Change-Id: If8f550dffc43887254f71aa0b487c50fa14d0627
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
Win32-OpenSSH uses a named Windows pipe for communication. Implement
a connector for this mechanism using JNA. Choose the appropriate
connector based on the setting of the 'identityAgent' parameter.
Bug: 577053
Change-Id: I205f07fb33654aa18ca5db92706e65544ce38641
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
Handle the 'none' value, and change the value to select Pageant to
something that looks like an absolute UNC path name to avoid it's
handled as an relative path name.
Bug: 577053
Change-Id: I4ccf047abbc1def50e2782319e4fa7c744069401
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
Bump the japicmp base version to 6.0.0.202111291000-r and configure
the o.e.j.ssh.apache and o.e.j.ssh.apache.agent bundles to ignore
internal classes.
Change-Id: Id95350c73b9141e1583f9de5fb6ab2496c7407d9
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
Once a factory supports different SSH agents on the same platform,
which is planned for Windows once we use Apache MINA sshd 2.8.0,
client code may need to have a way to specify which SSH agent shall
be used when the SSH config doesn't define anything.
Add a mechanism by which a ConnectorFactory can tell what Connectors
it may provide. Client code can use this to set the identityAgent
parameter of ConnectorFactory.create() to the wanted default if it
would be null otherwise.
A ConnectorDescriptor is a pair of strings: an internal name, and a
display name. The latter is included because client code might want to
communicate agent names to the user, be it in error messages or in some
chooser dialog where a user could define which of several alternative
SSH agents should be used as default. The internal name is intended to
be used in the IdentityAgent directive in ~/.ssh/config.
Also make the ConnectorFactory discovered via the ServiceLoader
accessible and overrideable. Provide static get/setDefault() methods,
similar to the SshSessionFactory itself.
Change-Id: Ie3d077395d32dfddc72bc8627e92b23636938182
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
Add a simple SSH agent connector using JNA. Include com.sum.jna and
com.sun.jna.platform in the target platform.
JNA is used to communicate through Unix domain sockets with ssh-agent,
and if on Windows, to communicate via shared memory with Pageant.
The new bundle o.e.j.ssh.apache.agent is an OSGi fragment so that
the java.util.ServiceLoader can find the provided factory without
further ado in OSGi environments.
Adapt both maven and bazel builds to include the new bundle.
Manually tested on OS X, CentOS 7, and Win10 with Pageant 0.76. Tested
by installing JGit built from this change into freshly downloaded
Eclipse 2021-12 M1, and then doing git fetches via SSH with different
~/.ssh/config settings (explicit IdentityFile, without any but a key in
the agent, with no keys and a key in the agent and IdentitiesOnly=yes
(must fail)).
Bug: 541274
Bug: 541275
Change-Id: I34e85467293707dbad1eb44d1f40fc2e70ba3622
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>
Thomas Wolf