Fix javadoc warnings

CHANGELOG.md

@@ -5,10 +5,9 @@ SPDX-License-Identifier: CC0-1.0
 
 # Cert-D-Java Changelog
 
-## 0.1.1-SNAPSHOT
+## 0.1.1
 - Bump `slf4j` to `1.7.36`
-- Bump `logback` to `1.2.11`
-- 
+- Bump `logback` to `1.2.11` 
 
 ## 0.1.0
-- Initial Release
+- Initial Release

pgp-cert-d-java/src/main/java/pgp/cert_d/FilenameResolver.java

@@ -28,7 +28,8 @@ public class FilenameResolver {
      *
      * @param fingerprint fingerprint
      * @return absolute certificate file location
-     * @throws BadNameException
+     *
+     * @throws BadNameException if the given fingerprint string is not a fingerprint
      */
     public File getCertFileByFingerprint(String fingerprint) throws BadNameException {
         if (!isFingerprint(fingerprint)) {
@@ -41,6 +42,15 @@ public class FilenameResolver {
         return file;
     }
 
+    /**
+     * Calculate the file location for the certification addressed using the given special name.
+     * For known special names, see {@link SpecialNames}.
+     *
+     * @param specialName special name (e.g. "trust-root")
+     * @return absolute certificate file location
+     *
+     * @throws BadNameException in case the given special name is not known
+     */
     public File getCertFileBySpecialName(String specialName) throws BadNameException {
         if (!isSpecialName(specialName)) {
             throw new BadNameException();

pgp-cert-d-java/src/main/java/pgp/cert_d/LockingMechanism.java

@@ -11,6 +11,9 @@ public interface LockingMechanism {
     /**
      * Lock the store for writes.
      * Readers can continue to use the store and will always see consistent certs.
+     *
+     * @throws IOException in case of an IO error
+     * @throws InterruptedException if the thread gets interrupted
      */
     void lockDirectory() throws IOException, InterruptedException;
 
@@ -19,11 +22,15 @@ public interface LockingMechanism {
      * Return false without locking the store in case the store was already locked.
      *
      * @return true if locking succeeded, false otherwise
+     *
+     * @throws IOException in case of an IO error
      */
     boolean tryLockDirectory() throws IOException;
 
     /**
      * Release the directory write-lock acquired via {@link #lockDirectory()}.
+     *
+     * @throws IOException in case of an IO error
      */
     void releaseDirectory() throws IOException;
 

pgp-certificate-store/src/main/java/pgp/certificate_store/Certificate.java

@@ -21,6 +21,7 @@ public abstract class Certificate {
      * Return an {@link InputStream} of the binary representation of the certificate.
      *
      * @return input stream
+     * @throws IOException in case of an IO error
      */
     public abstract InputStream getInputStream() throws IOException;
 
@@ -29,8 +30,15 @@ public abstract class Certificate {
      * The tag is a checksum calculated over the binary representation of the certificate.
      *
      * @return tag
+     * @throws IOException in case of an IO error
      */
     public abstract String getTag() throws IOException;
 
+    /**
+     * Return a {@link Set} containing key-ids of subkeys.
+     *
+     * @return subkeys
+     * @throws IOException in case of an IO error
+     */
     public abstract Set<Long> getSubkeyIds() throws IOException;
 }

pgp-certificate-store/src/main/java/pgp/certificate_store/CertificateDirectory.java

@@ -30,6 +30,8 @@ public interface CertificateDirectory {
      * @return certificate or null
      *
      * @throws IOException in case of an IO-error
+     * @throws BadNameException if the identifier is invalid
+     * @throws BadDataException if the certificate file contains invalid data
      */
     Certificate getCertificate(String identifier)
             throws IOException, BadNameException, BadDataException;
@@ -44,6 +46,8 @@ public interface CertificateDirectory {
      * @return changed certificate or null
      *
      * @throws IOException in case of an IO-error
+     * @throws BadNameException if the identifier is invalid
+     * @throws BadDataException if the certificate file contains invalid data
      */
     Certificate getCertificateIfChanged(String identifier, String tag)
             throws IOException, BadNameException, BadDataException;
@@ -63,6 +67,7 @@ public interface CertificateDirectory {
      *
      * @throws IOException in case of an IO-error
      * @throws InterruptedException in case the inserting thread gets interrupted
+     * @throws BadDataException if the data stream does not contain valid OpenPGP data
      */
     Certificate insertCertificate(InputStream data, MergeCallback merge)
             throws IOException, InterruptedException, BadDataException;
@@ -83,6 +88,7 @@ public interface CertificateDirectory {
      * @return merged certificate or null if the store cannot be locked
      *
      * @throws IOException in case of an IO-error
+     * @throws BadDataException if the data stream does not contain valid OpenPGP data
      */
     Certificate tryInsertCertificate(InputStream data, MergeCallback merge)
             throws IOException, BadDataException;
@@ -98,11 +104,15 @@ public interface CertificateDirectory {
      * This method will block until a write-lock on the store can be acquired. If you cannot afford blocking,
      * consider to use {@link #tryInsertCertificateBySpecialName(String, InputStream, MergeCallback)}  instead.
      *
+     * @param specialName special name of the certificate
      * @param data input stream containing the new certificate instance
      * @param merge callback for merging with an existing certificate instance
      * @return merged certificate or null if the store cannot be locked
      *
      * @throws IOException in case of an IO-error
+     * @throws InterruptedException if the thread is interrupted
+     * @throws BadDataException if the certificate file does not contain valid OpenPGP data
+     * @throws BadNameException if the special name is unknown
      */
     Certificate insertCertificateBySpecialName(String specialName, InputStream data, MergeCallback merge)
             throws IOException, InterruptedException, BadDataException, BadNameException;
@@ -120,11 +130,14 @@ public interface CertificateDirectory {
      * However, if the write-lock is available, this method will acquire the lock, write to the store, release the lock
      * and return the written certificate.
      *
+     * @param specialName special name for the certificate
      * @param data input stream containing the new certificate instance
      * @param merge callback for merging with an existing certificate instance
      * @return merged certificate or null if the store cannot be locked
      *
      * @throws IOException in case of an IO-error
+     * @throws BadDataException if the data stream does not contain valid OpenPGP data
+     * @throws BadNameException if the special name is not known
      */
     Certificate tryInsertCertificateBySpecialName(String specialName, InputStream data, MergeCallback merge)
             throws IOException, BadDataException, BadNameException;

pgp-certificate-store/src/main/java/pgp/certificate_store/MergeCallback.java

@@ -19,6 +19,8 @@ public interface MergeCallback {
      * @param data certificate
      * @param existing optional already existing copy of the certificate
      * @return merged certificate
+     *
+     * @throws IOException in case of an IO error
      */
     Certificate merge(Certificate data, Certificate existing) throws IOException;
 

pgp-certificate-store/src/main/java/pgp/certificate_store/SubkeyLookup.java

@@ -16,6 +16,8 @@ public interface SubkeyLookup {
      *
      * @param subkeyId subkey id
      * @return fingerprint of the certificate
+     *
+     * @throws IOException in case of an IO error
      */
     Set<String> getCertificateFingerprintsForSubkeyId(long subkeyId) throws IOException;
 
@@ -25,6 +27,7 @@ public interface SubkeyLookup {
      *
      * @param certificate certificate fingerprint
      * @param subkeyIds subkey ids
+     *
      * @throws IOException in case of an IO error
      */
     void storeCertificateSubkeyIds(String certificate, List<Long> subkeyIds) throws IOException;