Fixing javadoc related warnings.

Signed-off-by: Max Lambrecht <maxlambrecht@gmail.com>

build.gradle

@@ -15,13 +15,18 @@ subprojects {
 
     apply plugin: 'java-library'
 
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+
     java {
         withJavadocJar()
         withSourcesJar()
     }
 
-    sourceCompatibility = JavaVersion.VERSION_1_8
+    javadoc {
-    targetCompatibility = JavaVersion.VERSION_1_8
+        exclude "**/grpc/**"
+        exclude "**/internal/**"
+    }
 
     ext {
         jupiterVersion = '5.6.2'

java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundle.java

@@ -114,7 +114,7 @@ public class JwtBundle implements BundleSource<JwtBundle> {
     }
 
     /**
-     * Returns the JWT authorities in the bundle, keyed by key ID.
+     * @return the JWT authorities in the bundle, keyed by key ID.
      */
     public Map<String, PublicKey> getJwtAuthorities() {
         return Collections.unmodifiableMap(jwtAuthorities);
@@ -136,7 +136,10 @@ public class JwtBundle implements BundleSource<JwtBundle> {
     }
 
     /**
-     * Returns true if the bundle has a JWT authority with the given key ID.
+     * Looks for a JWT authority id in the JWT bundle.
+     *
+     * @param keyId id of a JWT Authority
+     * @return true if the bundle has a JWT authority with the given key ID.
      */
     public boolean hasJwtAuthority(String keyId) {
         return jwtAuthorities.containsKey(keyId);
@@ -158,6 +161,8 @@ public class JwtBundle implements BundleSource<JwtBundle> {
 
     /**
      * Removes the JWT authority identified by the key ID from the bundle.
+     *
+     * @param keyId The key id of the JWT authority to be removed
      */
     public void removeJwtAuthority(String keyId) {
         jwtAuthorities.remove(keyId);

java-spiffe-core/src/main/java/io/spiffe/bundle/jwtbundle/JwtBundleSet.java

@@ -56,7 +56,7 @@ public class JwtBundleSet implements BundleSource<JwtBundle> {
     }
 
     /**
-     * Returns the map of JWT bundles keyed by trust domain.
+     * @return the map of JWT bundles keyed by trust domain.
      */
     public Map<TrustDomain, JwtBundle> getBundles() {
         return Collections.unmodifiableMap(bundles);

java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509Bundle.java

@@ -107,7 +107,7 @@ public class X509Bundle implements BundleSource<X509Bundle> {
     }
 
     /**
-     * Returns the X.509 Authorities in the bundle.
+     * @return the X.509 Authorities in the bundle.
      */
     public Set<X509Certificate> getX509Authorities() {
         return Collections.unmodifiableSet(x509Authorities);
@@ -115,6 +115,8 @@ public class X509Bundle implements BundleSource<X509Bundle> {
 
     /**
      * Checks if the given X.509 authority exists in the bundle.
+     * @param x509Authority an X.509 certificate
+     * @return boolean true if the x509Authority is present in the X.509 bundle, false otherwise
      */
     public boolean hasX509Authority(X509Certificate x509Authority) {
         return x509Authorities.contains(x509Authority);
@@ -122,6 +124,7 @@ public class X509Bundle implements BundleSource<X509Bundle> {
 
     /**
      * Adds an X.509 authority to the bundle.
+     * @param x509Authority an X.509 certificate
      */
     public void addX509Authority(X509Certificate x509Authority) {
         x509Authorities.add(x509Authority);
@@ -129,6 +132,7 @@ public class X509Bundle implements BundleSource<X509Bundle> {
 
     /**
      * Removes an X.509 authority from the bundle.
+     * @param x509Authority an X.509 certificate
      */
     public void removeX509Authority(X509Certificate x509Authority) {
         x509Authorities.remove(x509Authority);

java-spiffe-core/src/main/java/io/spiffe/bundle/x509bundle/X509BundleSet.java

@@ -66,7 +66,7 @@ public class X509BundleSet implements BundleSource<X509Bundle> {
     }
 
     /**
-     * Returns the X.509 bundles of this X.509 Bundle Set.
+     * @return the X.509 bundles of this X.509 Bundle Set.
      */
     public Map<TrustDomain, X509Bundle> getBundles() {
         return Collections.unmodifiableMap(bundles);

java-spiffe-core/src/main/java/io/spiffe/svid/jwtsvid/JwtSvid.java

@@ -165,7 +165,7 @@ public class JwtSvid {
     }
 
     /**
-     * Returns a copy of the expiration date time of the JWT SVID.
+     * @return a copy of the expiration date time of the JWT SVID.
      */
     public Date getExpiry() {
         // defensive copying to prevent exposing a mutable object

java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509Svid.java

@@ -86,7 +86,7 @@ public class X509Svid implements X509SvidSource {
     }
 
     /**
-     * Returns the chain of certificates as an array of {@link X509Certificate}
+     * @return the chain of certificates as an array of {@link X509Certificate}
      */
     public X509Certificate[] getChainArray() {
         return chain.toArray(new X509Certificate[0]);

java-spiffe-core/src/main/java/io/spiffe/svid/x509svid/X509SvidValidator.java

@@ -26,6 +26,7 @@ public class X509SvidValidator {
      * @param chain            a list representing the chain of X.509 certificates to be validated
      * @param x509BundleSource a {@link BundleSource } to provide the authorities
      * @throws CertificateException is the chain cannot be verified with an authority from the X.509 bundle source
+     * @throws BundleNotFoundException if no X.509 bundle for the trust domain could be found in the X.509 bundle source
      * @throws NullPointerException if the given chain or 509BundleSource are null
      */
     public static void verifyChain(

java-spiffe-core/src/main/java/io/spiffe/workloadapi/Address.java

@@ -26,7 +26,7 @@ public class Address {
     private static final List<String> VALID_SCHEMES = Arrays.asList(UNIX_SCHEME, TCP_SCHEME);
 
     /**
-     * Returns the default Workload API address hold by the system environment variable
+     * @return the default Workload API address hold by the system environment variable
      * defined by SOCKET_ENV_VARIABLE.
      */
     public static String getDefaultAddress() {

java-spiffe-core/src/main/java/io/spiffe/workloadapi/WorkloadApiClient.java

@@ -66,6 +66,7 @@ public class WorkloadApiClient implements Closeable {
      * Creates a new Workload API client using the default socket endpoint address.
      *
      * @return a {@link WorkloadApiClient}
+     * @throws SocketEndpointAddressException if the Workload API socket endpoint address is not valid
      * @see Address#getDefaultAddress()
      */
     public static WorkloadApiClient newClient() throws SocketEndpointAddressException {
@@ -80,6 +81,7 @@ public class WorkloadApiClient implements Closeable {
      *
      * @param options {@link ClientOptions}
      * @return a {@link WorkloadApiClient}
+     * @throws SocketEndpointAddressException if the Workload API socket endpoint address is not valid
      */
     public static WorkloadApiClient newClient(@NonNull ClientOptions options) throws SocketEndpointAddressException {
         String spiffeSocketPath;
@@ -150,6 +152,7 @@ public class WorkloadApiClient implements Closeable {
     /**
      * One-shot blocking fetch call to get an X.509 context.
      *
+     * @return an instance of a {@link X509Context} containing the X.509 materials fetched from the Workload API
      * @throws X509ContextException if there is an error fetching or processing the X.509 context
      */
     public X509Context fetchX509Context() throws X509ContextException {

java-spiffe-core/src/main/java/io/spiffe/workloadapi/internal/ManagedChannelWrapper.java

@@ -18,6 +18,9 @@ public class ManagedChannelWrapper implements Closeable {
 
     /**
      * Constructor
+     *
+     * @param  managedChannel an instance of {@link ManagedChannel}
+     * @param eventLoopGroup an instance of {@link EventLoopGroup}
      */
     public ManagedChannelWrapper(ManagedChannel managedChannel, EventLoopGroup eventLoopGroup) {
         this.managedChannel = managedChannel;
@@ -26,6 +29,8 @@ public class ManagedChannelWrapper implements Closeable {
 
     /**
      * Constructor
+     *
+     * @param managedChannel a {@link ManagedChannel}
      */
     public ManagedChannelWrapper(ManagedChannel managedChannel) {
         this.managedChannel = managedChannel;

java-spiffe-core/src/main/java/io/spiffe/workloadapi/retry/RetryHandler.java

@@ -23,6 +23,8 @@ public class RetryHandler {
     /**
      * Schedule to execute a Runnable, based on the backoff policy
      * Updates the next delay and retries count
+     *
+     * @param runnable the task to be scheduled for execution
      */
     public void scheduleRetry(Runnable runnable) {
         if (backoffPolicy.didNotReachMaxRetries(retryCount)) {