Add Javadoc to commands and adjust CI steps

Author: intisy

.github/workflows/build.yml

@@ -35,7 +35,7 @@ jobs:
         run: ./gradlew test --tests "io.github.intisy.docker.ModelTest" --tests "io.github.intisy.docker.DockerClientBuilderTest" --info
         shell: bash
 
-      - name: Run tests (Linux - excluding daemon startup tests)
+      - name: Run tests
         if: matrix.test-type == 'integration'
         run: ./gradlew test --tests "io.github.intisy.docker.ModelTest" --tests "io.github.intisy.docker.DockerClientBuilderTest" --tests "io.github.intisy.docker.WslDiagnosticTest" --info
         shell: bash
@@ -62,7 +62,7 @@ jobs:
       - name: Grant execute permission for gradlew
         run: chmod +x gradlew
 
-      - name: Run build with Gradle Wrapper (skip tests - already run in test job)
+      - name: Run build with Gradle Wrapper
         run: ./gradlew build -x test -Partifact_version=${{ github.ref_name }}
 
       - name: Create Release and Upload Jar

src/main/java/io/github/intisy/docker/DockerClient.java

@@ -21,6 +21,21 @@
  *     .withHost("unix:///var/run/docker.sock")
  *     .build();
  *
+ * // List containers
+ * List<Container> containers = client.listContainers().withShowAll(true).exec();
+ *
+ * // Pull and run a container
+ * client.pullImage("nginx:alpine").exec(5, TimeUnit.MINUTES);
+ * CreateContainerResponse response = client.createContainer("nginx:alpine")
+ *     .withName("my-nginx")
+ *     .exec();
+ * client.startContainer(response.getId()).exec();
+ *
+ * // Clean up
+ * client.stopContainer(response.getId()).exec();
+ * client.removeContainer(response.getId()).exec();
+ * }</pre>
+ *
  * @author Finn Birich
  */
 public class DockerClient implements Closeable {

src/main/java/io/github/intisy/docker/DockerProvider.java

@@ -113,12 +113,20 @@ public static DockerProvider get() {
      * Start the Docker daemon.
      * This will always start a new managed Docker daemon instance.
      * The daemon will use isolated paths to avoid conflicts with Docker Desktop or other instances.
+     *
+     * @throws IOException if an I/O error occurs during startup
+     * @throws InterruptedException if the thread is interrupted during startup
+      * @throws IOException if an I/O error occurs during startup
+      * @throws InterruptedException if the thread is interrupted during startup
      */
     public abstract void start() throws IOException, InterruptedException;
 
     /**
      * Get a DockerClient for interacting with the Docker daemon.
      * The client can be used to manage containers, images, volumes, networks, etc.
+     *
+     * @return the DockerClient instance
+      * @return the DockerClient instance
      */
     public abstract DockerClient getClient();
 
@@ -131,6 +139,9 @@ public static DockerProvider get() {
     /**
      * Ensure Docker is installed.
      * Downloads and installs Docker if necessary.
+     *
+     * @throws IOException if an I/O error occurs during installation
+      * @throws IOException if an I/O error occurs during installation
      */
     public abstract void ensureInstalled() throws IOException;
 

src/main/java/io/github/intisy/docker/command/container/CreateContainerCmd.java

@@ -136,6 +136,11 @@ public CreateContainerCmd withBind(String hostPath, String containerPath) {
 
     /**
      * Add a bind mount with read-only option.
+      *
+      * @param hostPath the host path to mount
+      * @param containerPath the container path to mount to
+      * @param readOnly whether the mount should be read-only
+      * @return this command instance
      */
     public CreateContainerCmd withBind(String hostPath, String containerPath, boolean readOnly) {
         if (config.getHostConfig() == null) {
@@ -191,6 +196,9 @@ public CreateContainerCmd withRestartPolicy(HostConfig.RestartPolicy restartPoli
 
     /**
      * Set memory limit in bytes.
+      *
+      * @param memory the memory limit in bytes
+      * @return this command instance
      */
     public CreateContainerCmd withMemory(long memory) {
         if (config.getHostConfig() == null) {

src/main/java/io/github/intisy/docker/command/container/ExecStartCmd.java

@@ -58,6 +58,8 @@ public void exec() {
 
     /**
      * Execute the command and stream output.
+      *
+      * @param callback the callback for streaming output
      */
     public void exec(StreamCallback<String> callback) {
         try {

src/main/java/io/github/intisy/docker/command/container/KillContainerCmd.java

@@ -24,6 +24,9 @@ public KillContainerCmd(DockerHttpClient client, String containerId) {
 
     /**
      * Set the signal to send (default: SIGKILL).
+      *
+      * @param signal the signal to send (e.g. SIGTERM)
+      * @return this command instance
      */
     public KillContainerCmd withSignal(String signal) {
         this.signal = signal;

src/main/java/io/github/intisy/docker/command/container/ListContainersCmd.java

@@ -28,6 +28,9 @@ public ListContainersCmd(DockerHttpClient client) {
 
     /**
      * Show all containers (default shows just running).
+      *
+      * @param showAll true to show all containers, false for running only
+      * @return this command instance
      */
     public ListContainersCmd withShowAll(boolean showAll) {
         this.showAll = showAll;
@@ -54,6 +57,9 @@ public ListContainersCmd withFilter(String key, String... values) {
 
     /**
      * Filter by status (created, restarting, running, removing, paused, exited, dead).
+      *
+      * @param status the status to filter by
+      * @return this command instance
      */
     public ListContainersCmd withStatusFilter(String status) {
         return withFilter("status", status);

src/main/java/io/github/intisy/docker/command/container/LogsContainerCmd.java

@@ -31,6 +31,9 @@ public LogsContainerCmd(DockerHttpClient client, String containerId) {
 
     /**
      * Follow log output (streaming).
+      *
+      * @param follow true to follow log output
+      * @return this command instance
      */
     public LogsContainerCmd withFollow(boolean follow) {
         this.follow = follow;
@@ -49,6 +52,9 @@ public LogsContainerCmd withStderr(boolean stderr) {
 
     /**
      * Show logs since timestamp (Unix timestamp or RFC3339).
+      *
+      * @param since the start timestamp
+      * @return this command instance
      */
     public LogsContainerCmd withSince(String since) {
         this.since = since;
@@ -57,6 +63,9 @@ public LogsContainerCmd withSince(String since) {
 
     /**
      * Show logs until timestamp (Unix timestamp or RFC3339).
+      *
+      * @param until the end timestamp
+      * @return this command instance
      */
     public LogsContainerCmd withUntil(String until) {
         this.until = until;
@@ -70,6 +79,9 @@ public LogsContainerCmd withTimestamps(boolean timestamps) {
 
     /**
      * Only return the last N lines.
+      *
+      * @param tail the number of lines to return
+      * @return this command instance
      */
     public LogsContainerCmd withTail(int tail) {
         this.tail = tail;
@@ -78,6 +90,8 @@ public LogsContainerCmd withTail(int tail) {
 
     /**
      * Execute the command and return logs as a string.
+      *
+      * @return the log output as a string
      */
     public String exec() {
         try {
@@ -101,6 +115,8 @@ public String exec() {
 
     /**
      * Execute the command with streaming callback.
+      *
+      * @param callback the callback for streaming log lines
      */
     public void exec(StreamCallback<String> callback) {
         try {

src/main/java/io/github/intisy/docker/command/container/RestartContainerCmd.java

@@ -24,6 +24,9 @@ public RestartContainerCmd(DockerHttpClient client, String containerId) {
 
     /**
      * Set timeout in seconds before killing the container.
+      *
+      * @param timeout seconds to wait before killing
+      * @return this command instance
      */
     public RestartContainerCmd withTimeout(int timeout) {
         this.timeout = timeout;

src/main/java/io/github/intisy/docker/command/container/StopContainerCmd.java

@@ -25,6 +25,9 @@ public StopContainerCmd(DockerHttpClient client, String containerId) {
 
     /**
      * Set timeout in seconds before killing the container.
+      *
+      * @param timeout seconds to wait before killing
+      * @return this command instance
      */
     public StopContainerCmd withTimeout(int timeout) {
         this.timeout = timeout;