Fix Javadoc warnings by adding missing @param, @return and @throws tags (#46)

Author: Fivell

src/main/java/com/didww/sdk/DidwwClient.java

@@ -194,7 +194,13 @@ public Repository<RequirementValidation> requirementValidations() {
 
     /**
      * Uploads one encrypted file to /encrypted_files as multipart/form-data.
-     * Returns encrypted file IDs provided by API response.
+     *
+     * @param encryptedData encrypted file bytes to upload
+     * @param fileName      original file name sent as the multipart part name
+     * @param fingerprint   encryption key fingerprint identifying the public key used
+     * @param description   optional human-readable description for the file (may be {@code null})
+     * @return list of encrypted file IDs returned by the API
+     * @throws DidwwClientException if the upload fails or the response is unexpected
      */
     public List<String> uploadEncryptedFile(byte[] encryptedData,
                                             String fileName,
@@ -257,6 +263,10 @@ public List<String> uploadEncryptedFile(byte[] encryptedData,
 
     /**
      * Downloads an export file to the given path.
+     *
+     * @param url         URL of the export file to download
+     * @param destination local path where the file will be written
+     * @throws DidwwClientException if the download fails or the response body is empty
      */
     public void downloadExport(String url, Path destination) {
         Request request = new Request.Builder().url(url).get().build();
@@ -278,6 +288,10 @@ public void downloadExport(String url, Path destination) {
 
     /**
      * Downloads a gzip-compressed export file (.csv.gz) and writes the decompressed CSV to the given path.
+     *
+     * @param url         URL of the gzip-compressed export file to download
+     * @param destination local path where the decompressed CSV will be written
+     * @throws DidwwClientException if the download or decompression fails
      */
     public void downloadAndDecompressExport(String url, Path destination) {
         Path tempFile;
@@ -342,6 +356,9 @@ public Builder readTimeout(Duration readTimeout) {
 
         /**
          * Overrides the base URL from the credentials environment. Useful for testing.
+         *
+         * @param baseUrl base URL to use instead of the environment default
+         * @return this builder
          */
         public Builder baseUrl(String baseUrl) {
             this.baseUrl = baseUrl;
@@ -351,6 +368,9 @@ public Builder baseUrl(String baseUrl) {
         /**
          * Sets a custom OkHttpClient.Builder for advanced configuration such as proxy,
          * SSL, interceptors, etc. The API key interceptor will be added automatically.
+         *
+         * @param httpClientBuilder custom OkHttpClient builder to use as the base
+         * @return this builder
          */
         public Builder httpClientBuilder(OkHttpClient.Builder httpClientBuilder) {
             this.httpClientBuilder = httpClientBuilder;

src/main/java/com/didww/sdk/SdkVersion.java

@@ -40,13 +40,17 @@ private SdkVersion() {
     /**
      * Returns the SDK version string (e.g. {@code "1.0.0"}).
      * Falls back to {@code "unknown"} when the properties file is absent.
+     *
+     * @return SDK version string
      */
     public static String get() {
         return VERSION;
     }
 
     /**
      * Returns the full User-Agent value, e.g. {@code "didww-java-sdk/1.0.0"}.
+     *
+     * @return User-Agent header value
      */
     public static String userAgent() {
         return "didww-java-sdk/" + VERSION;

src/main/java/com/didww/sdk/exception/DidwwApiException.java

@@ -77,6 +77,8 @@ public static class ApiError {
         /**
          * Returns {@code detail} if present, otherwise falls back to {@code title},
          * or {@code "Unknown error"} when both are absent.
+         *
+         * @return human-readable error message
          */
         @JsonIgnore
         public String getMessage() {

src/main/java/com/didww/sdk/http/ApiKeyInterceptor.java

@@ -16,6 +16,13 @@ public ApiKeyInterceptor(String apiKey) {
         this.apiKey = apiKey;
     }
 
+    /**
+     * Adds authentication and versioning headers to every outgoing request.
+     *
+     * @param chain OkHttp interceptor chain
+     * @return response from the next interceptor or the network
+     * @throws IOException if the request could not be executed
+     */
     @Override
     public Response intercept(Chain chain) throws IOException {
         Request original = chain.request();

src/main/java/com/didww/sdk/repository/ReadOnlyRepository.java

@@ -84,6 +84,14 @@ public ApiResponse<T> find(String id, QueryParams params) {
         }
     }
 
+    /**
+     * Throws {@link DidwwApiException} when the response status is not successful,
+     * parsing API error objects from the response body when available.
+     *
+     * @param response OkHttp response to inspect
+     * @throws IOException         if the response body cannot be read
+     * @throws DidwwApiException   if the response indicates an API error
+     */
     protected void handleErrorResponse(Response response) throws IOException {
         if (!response.isSuccessful()) {
             String body = response.body() != null ? response.body().string() : "";
@@ -107,6 +115,14 @@ protected void handleErrorResponse(Response response) throws IOException {
         }
     }
 
+    /**
+     * Returns the response body as a byte array.
+     *
+     * @param response OkHttp response whose body will be consumed
+     * @return response body bytes
+     * @throws IOException            if the body cannot be read
+     * @throws DidwwClientException   if the response body is absent
+     */
     protected byte[] getResponseBody(Response response) throws IOException {
         ResponseBody body = response.body();
         if (body == null) {