add documentation for each method

Author: doxthree

java/src/main/java/de/gdata/vaas/Vaas.java

@@ -138,13 +138,16 @@ private HttpRequest.Builder CreateHttpRequestBuilderWithHeaders(URI uri, String
     }
 
     /**
-     * Asynchronously retrieves a VaasVerdict for the given SHA-256 hash.
-     * This method uses cache and hash lookup options by default. 
+     * Asynchronously retrieves a {@link CompletableFuture} containing the
+     * {@link VaasVerdict} for the given SHA-256 hash.
+     * This method uses cache and hash lookup options by default.
      *
      * @param sha256 the SHA-256 hash to retrieve the verdict for
-     * @return A CompletableFuture that will complete with the VaasVerdict.
-     * @throws IOException If an I/O error occurs during the request.
-     * @throws InterruptedException If the operation is interrupted.
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict} for
+     *         the hash
+     * @throws IOException                 If an I/O error occurs during the
+     *                                     request.
+     * @throws InterruptedException        If the operation is interrupted.
      * @throws VaasAuthenticationException If there is an authentication error.
      */
     @Override
@@ -157,13 +160,17 @@ public CompletableFuture<VaasVerdict> forSha256Async(Sha256 sha256)
     }
 
     /**
-     * Asynchronously retrieves a VaasVerdict for the given SHA-256 hash.
+     * Asynchronously retrieves a {@link CompletableFuture} containing the
+     * {@link VaasVerdict} for the given SHA-256 hash.
      *
-     * @param sha256 the SHA-256 hash to retrieve the verdict for
-     * @param options The options to customize the request, such as cache usage and hash lookup.
-     * @return A CompletableFuture that will complete with the VaasVerdict.
-     * @throws IOException If an I/O error occurs during the request.
-     * @throws InterruptedException If the operation is interrupted.
+     * @param sha256  the SHA-256 hash to retrieve the verdict for
+     * @param options The options to customize the request, such as using the cache
+     *                and hash lookup.
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict} for
+     *         the hash
+     * @throws IOException                 If an I/O error occurs during the
+     *                                     request.
+     * @throws InterruptedException        If the operation is interrupted.
      * @throws VaasAuthenticationException If there is an authentication error.
      */
     @Override
@@ -183,13 +190,15 @@ public CompletableFuture<VaasVerdict> forSha256Async(Sha256 sha256, ForSha256Opt
     }
 
     /**
-     * Retrieves a VaasVerdict for the given SHA-256 hash.
+     * Retrieves a {@link VaasVerdict} for the given SHA-256 hash.
+     * This method uses cache and hash lookup options by default.
      *
      * @param sha256 the SHA-256 hash to retrieve the verdict for
-     * @return the VaasVerdict for the given SHA-256 hash
-     * @throws InterruptedException if the thread is interrupted while waiting for the result
-     * @throws ExecutionException if the computation threw an exception
-     * @throws IOException if an I/O error occurs
+     * @return the {@link VaasVerdict} for the given SHA-256 hash
+     * @throws InterruptedException        if the thread is interrupted while
+     *                                     waiting for the result
+     * @throws ExecutionException          if the computation threw an exception
+     * @throws IOException                 if an I/O error occurs
      * @throws VaasAuthenticationException if there is an authentication error
      */
     @Override
@@ -198,12 +207,41 @@ public VaasVerdict forSha256(Sha256 sha256)
         return forSha256Async(sha256).get();
     }
 
+    /**
+     * Retrieves a {@link VaasVerdict} for the given SHA-256 hash.
+     * This method uses cache and hash lookup options by default.
+     *
+     * @param sha256  the SHA-256 hash to retrieve the verdict for
+     * @param options The options to customize the request, such as using the cache
+     *                and hash lookup.
+     * @return the {@link VaasVerdict} for the given SHA-256 hash
+     * @throws InterruptedException        if the thread is interrupted while
+     *                                     waiting for the result
+     * @throws ExecutionException          if the computation threw an exception
+     * @throws IOException                 if an I/O error occurs
+     * @throws VaasAuthenticationException if there is an authentication error
+     */
     @Override
     public VaasVerdict forSha256(Sha256 sha256, ForSha256Options options)
             throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
         return forSha256Async(sha256, options).get();
     }
 
+    /**
+     * Asynchronously processes a file and returns a {@link CompletableFuture}
+     * containing the {@link VaasVerdict}.
+     * This method uses default options for file processing, including using the
+     * cache and hash lookup.
+     *
+     * @param file the {@link Path} to the file to be processed
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict} for
+     *         the file
+     * @throws IOException                 if an I/O error occurs
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws VaasAuthenticationException if authentication fails
+     * @throws NoSuchAlgorithmException    if the algorithm for hash lookup is not
+     *                                     available
+     */
     @Override
     public CompletableFuture<VaasVerdict> forFileAsync(Path file)
             throws IOException, InterruptedException, VaasAuthenticationException, NoSuchAlgorithmException {
@@ -213,6 +251,23 @@ public CompletableFuture<VaasVerdict> forFileAsync(Path file)
         return forFileAsync(file, forFileOptions);
     }
 
+    /**
+     * Asynchronously processes a file and returns a {@link CompletableFuture}
+     * containing the {@link VaasVerdict}.
+     * This method uses default options for file processing, including using the
+     * cache and hash lookup.
+     *
+     * @param file    the {@link Path} to the file to be processed
+     * @param options The options to customize the request, such as using the cache
+     *                and hash lookup.
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict} for
+     *         the file
+     * @throws IOException                 if an I/O error occurs
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws VaasAuthenticationException if authentication fails
+     * @throws NoSuchAlgorithmException    if the algorithm for hash lookup is not
+     *                                     available
+     */
     @Override
     public CompletableFuture<VaasVerdict> forFileAsync(Path file, ForFileOptions options)
             throws IOException, InterruptedException, VaasAuthenticationException, NoSuchAlgorithmException {
@@ -254,23 +309,79 @@ public CompletableFuture<VaasVerdict> forFileAsync(Path file, ForFileOptions opt
                 })).orTimeout(this.config.getDefaultTimeoutInMs(), TimeUnit.MILLISECONDS);
     }
 
+    /**
+     * Processes a file and returns the {@link VaasVerdict}.
+     * This method uses default options for file processing, including using the
+     * cache and hash lookup.
+     *
+     * @param file the {@link Path} to the file to be processed
+     * @return the {@link VaasVerdict} for the file
+     * @throws IOException                 if an I/O error occurs
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws VaasAuthenticationException if authentication fails
+     * @throws NoSuchAlgorithmException    if the algorithm for hash lookup is not
+     *                                     available
+     */
     @Override
-    public VaasVerdict forFile(Path file) throws NoSuchAlgorithmException, InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
+    public VaasVerdict forFile(Path file) throws NoSuchAlgorithmException, InterruptedException, ExecutionException,
+            IOException, VaasAuthenticationException {
         return forFileAsync(file).get();
     }
 
+    /**
+     * Processes a file and returns the {@link VaasVerdict}.
+     *
+     * @param file    the {@link Path} to the file to be processed
+     * @param options The options to customize the request, such as using the cache
+     *                and hash lookup.
+     * @return the {@link VaasVerdict} for the file
+     * @throws IOException                 if an I/O error occurs
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws VaasAuthenticationException if authentication fails
+     * @throws NoSuchAlgorithmException    if the algorithm for hash lookup is not
+     *                                     available
+     */
     @Override
-    public VaasVerdict forFile(Path file, ForFileOptions options) throws NoSuchAlgorithmException, InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
+    public VaasVerdict forFile(Path file, ForFileOptions options) throws NoSuchAlgorithmException, InterruptedException,
+            ExecutionException, IOException, VaasAuthenticationException {
         return forFileAsync(file, options).get();
     }
 
+    /**
+     * Asynchronously processes a given input stream and returns a
+     * {@link CompletableFuture}
+     * containing the {@link VaasVerdict}.
+     * This method uses the hash lookup option by default.
+     *
+     * @param stream        the input stream to be processed
+     * @param contentLength the length of the content in the input stream
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict}
+     * @throws IOException                 if an I/O error occurs
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws VaasAuthenticationException if authentication fails
+     */
     @Override
-    public CompletableFuture<VaasVerdict> forStreamAsync(InputStream stream, long contentLength) throws IOException, InterruptedException, VaasAuthenticationException {
+    public CompletableFuture<VaasVerdict> forStreamAsync(InputStream stream, long contentLength)
+            throws IOException, InterruptedException, VaasAuthenticationException {
         var forStreamOptions = new ForStreamOptions();
         forStreamOptions.setUseHashLookup(true);
         return forStreamAsync(stream, contentLength, forStreamOptions);
     }
 
+    /**
+     * Asynchronously processes a given input stream and returns a
+     * {@link CompletableFuture}
+     * containing the {@link VaasVerdict}.
+     *
+     * @param inputStream   the input stream to be processed
+     * @param contentLength the length of the content in the input stream
+     * @param options       The options to customize the request, such as using the
+     *                      hash lookup.
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict}
+     * @throws IOException                 if an I/O error occurs
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws VaasAuthenticationException if authentication fails
+     */
     @Override
     public CompletableFuture<VaasVerdict> forStreamAsync(InputStream inputStream, long contentLength,
             ForStreamOptions options) throws IOException, InterruptedException, VaasAuthenticationException {
@@ -301,25 +412,83 @@ public CompletableFuture<VaasVerdict> forStreamAsync(InputStream inputStream, lo
                 })).orTimeout(this.config.getDefaultTimeoutInMs(), TimeUnit.MILLISECONDS);
     }
 
+    /**
+     * Processes a given input stream and returns the {@link VaasVerdict}.
+     * This method uses the hash lookup option by default.
+     *
+     * @param stream        the input stream to be processed
+     * @param contentLength the length of the content in the input stream
+     * @return the {@link VaasVerdict}
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws ExecutionException          if the computation threw an exception
+     * @throws IOException                 if an I/O error occurs
+     * @throws VaasAuthenticationException if there is an authentication error
+     */
     @Override
-    public VaasVerdict forStream(InputStream stream, long contentLength) throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
+    public VaasVerdict forStream(InputStream stream, long contentLength)
+            throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
         return forStreamAsync(stream, contentLength).get();
     }
 
+    /**
+     * Processes a given input stream and returns the {@link VaasVerdict}.
+     *
+     * @param stream        the input stream to be processed
+     * @param contentLength the length of the content in the input stream
+     * @param options       The options to customize the request, such as using the
+     *                      hash lookup.
+     * @return the {@link VaasVerdict}
+     * @throws InterruptedException        if the operation is interrupted
+     * @throws ExecutionException          if the computation threw an exception
+     * @throws IOException                 if an I/O error occurs
+     * @throws VaasAuthenticationException if there is an authentication error
+     */
     @Override
-    public VaasVerdict forStream(InputStream stream, long contentLength, ForStreamOptions options) throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
+    public VaasVerdict forStream(InputStream stream, long contentLength, ForStreamOptions options)
+            throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
         return forStreamAsync(stream, contentLength, options).get();
     }
 
+    /**
+     * Asynchronously retrieves a {@link CompletableFuture} containing the
+     * {@link VaasVerdict} for the given URL.
+     * This method uses hash lookup by default.
+     *
+     * @param url the URL to retrieve the verdict for
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict} for
+     *         the
+     *         URL
+     * @throws IOException                 If an I/O error occurs during the
+     *                                     request.
+     * @throws InterruptedException        If the operation is interrupted.
+     * @throws VaasAuthenticationException If there is an authentication error.
+     */
     @Override
-    public CompletableFuture<VaasVerdict> forUrlAsync(URL url) throws IOException, InterruptedException, VaasAuthenticationException {
+    public CompletableFuture<VaasVerdict> forUrlAsync(URL url)
+            throws IOException, InterruptedException, VaasAuthenticationException {
         var forUrlOptions = new ForUrlOptions();
         forUrlOptions.setUseHashLookup(true);
         return forUrlAsync(url, forUrlOptions);
     }
 
+    /**
+     * Asynchronously retrieves a {@link CompletableFuture} containing the
+     * {@link VaasVerdict} for the given URL.
+     *
+     * @param url     the URL to retrieve the verdict for
+     * @param options The options to customize the request, such as using hash
+     *                lookup.
+     * @return a {@link CompletableFuture} containing the {@link VaasVerdict} for
+     *         the
+     *         URL
+     * @throws IOException                 If an I/O error occurs during the
+     *                                     request.
+     * @throws InterruptedException        If the operation is interrupted.
+     * @throws VaasAuthenticationException If there is an authentication error.
+     */
     @Override
-    public CompletableFuture<VaasVerdict> forUrlAsync(URL url, ForUrlOptions options) throws IOException, InterruptedException, VaasAuthenticationException {
+    public CompletableFuture<VaasVerdict> forUrlAsync(URL url, ForUrlOptions options)
+            throws IOException, InterruptedException, VaasAuthenticationException {
         var params = Map.of("useHashLookup", String.valueOf(options.isUseHashLookup()));
         var urlsUri = this.config.getUrl() + "/urls";
         var urlAnalysisRequest = new UrlAnalysisRequest(url.toString(), options.isUseHashLookup());
@@ -350,13 +519,42 @@ public CompletableFuture<VaasVerdict> forUrlAsync(URL url, ForUrlOptions options
                 .orTimeout(this.config.getDefaultTimeoutInMs(), TimeUnit.MILLISECONDS);
     }
 
+    /**
+     * Retrieves a {@link VaasVerdict} for the given URL.
+     * This method uses hash lookup by default.
+     *
+     * @param url the URL to retrieve the verdict for
+     * @return the {@link VaasVerdict} for the URL
+     * @throws InterruptedException        if the thread is interrupted while
+     *                                     waiting
+     *                                     for the result
+     * @throws ExecutionException          if the computation threw an exception
+     * @throws IOException                 if an I/O error occurs
+     * @throws VaasAuthenticationException if there is an authentication error
+     */
     @Override
-    public VaasVerdict forUrl(URL url) throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
+    public VaasVerdict forUrl(URL url)
+            throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
         return forUrlAsync(url).get();
     }
 
+    /**
+     * Retrieves a {@link VaasVerdict} for the given URL.
+     *
+     * @param url     the URL to retrieve the verdict for
+     * @param options The options to customize the request, such as using hash
+     *                lookup.
+     * @return the {@link VaasVerdict} for the URL
+     * @throws InterruptedException        if the thread is interrupted while
+     *                                     waiting
+     *                                     for the result
+     * @throws ExecutionException          if the computation threw an exception
+     * @throws IOException                 if an I/O error occurs
+     * @throws VaasAuthenticationException if there is an authentication error
+     */
     @Override
-    public VaasVerdict forUrl(URL url, ForUrlOptions options) throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
+    public VaasVerdict forUrl(URL url, ForUrlOptions options)
+            throws InterruptedException, ExecutionException, IOException, VaasAuthenticationException {
         return forUrlAsync(url, options).get();
     }
 }

java/src/main/java/de/gdata/vaas/options/ForFileOptions.java

@@ -7,6 +7,19 @@
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
+/**
+ * Options for configuring forFile requests.
+ * 
+ * <p>This class provides configuration options for file processing, including
+ * whether to use cache, hash lookup, and an optional VaaS request ID.</p>
+ * 
+ * <p>Fields:</p>
+ * <ul>
+ *   <li>{@code boolean UseCache} - Indicates whether to use cache. Default is {@code true}.</li>
+ *   <li>{@code boolean UseHashLookup} - Indicates whether to use hash lookup. Default is {@code true}.</li>
+ *   <li>{@code String VaasRequestId} - Optional VaaS request ID. Can be {@code null}.</li>
+ * </ul>
+ */
 @AllArgsConstructor
 @NoArgsConstructor
 public class ForFileOptions {

java/src/main/java/de/gdata/vaas/options/ForSha256Options.java

@@ -9,6 +9,19 @@
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
+/**
+ * Options for configuring forSha256 requests.
+ * 
+ * <p>This class provides configuration options for SHA-256 processing, including
+ * whether to use cache, hash lookup, and a Vaas request ID.</p>
+ * 
+ * <p>Fields:</p>
+ * <ul>
+ *   <li>{@code boolean UseCache} - Indicates whether to use cache. Default is {@code true}.</li>
+ *   <li>{@code boolean UseHashLookup} - Indicates whether to use hash lookup. Default is {@code true}.</li>
+ *   <li>{@code String VaasRequestId} - The Vaas request ID. Default is a randomly generated UUID.</li>
+ * </ul>
+ */
 @AllArgsConstructor
 @NoArgsConstructor
 public class ForSha256Options {