Improve logging messages and javadoc per review feedback

- Differentiate cache skip message when cacheCompile=false vs true
- Change empty directory artifact log from warn to info level
- Add artifact examples to stagePreExistingArtifacts javadoc
- Add proper javadoc to collectCachedArtifactPaths method
- Fix resource leak: wrap Files.walk() in try-with-resources

Author: cowwoc

src/main/java/org/apache/maven/buildcache/CacheControllerImpl.java

@@ -611,7 +611,9 @@ public void save(
             boolean isPomProjectWithWork = "pom".equals(project.getPackaging()) && !completedExecution.isEmpty();
 
             if (!hasArtifactFile && !hasAttachedArtifacts && !isPomProjectWithWork) {
-                LOGGER.info("Skipping cache save: no artifacts to save (only metadata present)");
+                LOGGER.info(
+                        "Skipping cache save: no artifacts to save ({}only metadata present)",
+                        cacheCompile ? "" : "cacheCompile=false, ");
                 return;
             }
 
@@ -711,7 +713,7 @@ private void saveDirectoryArtifact(
             // Clean up temp file after it's been saved to cache
             Files.deleteIfExists(tempZip);
         } else {
-            LOGGER.warn("Directory artifact has no files to cache: {}", originalFile);
+            LOGGER.info("Skipping empty directory artifact: {}", originalFile);
         }
     }
 
@@ -1167,6 +1169,14 @@ public FileVisitResult visitFile(Path path, BasicFileAttributes basicFileAttribu
     /**
      * Move pre-existing build artifacts to staging directory to prevent caching stale files.
      *
+     * <p><b>Artifacts Staged:</b>
+     * <ul>
+     *   <li>{@code target/classes} - Compiled main classes directory</li>
+     *   <li>{@code target/test-classes} - Compiled test classes directory</li>
+     *   <li>{@code target/*.jar} - Main project artifact (JAR/WAR files)</li>
+     *   <li>Other directories configured via {@code attachedOutputs} in cache configuration</li>
+     * </ul>
+     *
      * <p><b>DESIGN RATIONALE - Staleness Detection via Staging Directory:</b>
      *
      * <p>This approach solves three critical problems that timestamp-based checking cannot handle:
@@ -1277,7 +1287,19 @@ public void stagePreExistingArtifacts(MavenSession session, MavenProject project
     }
 
     /**
-     * Collect paths to all artifacts that will be cached (main artifact + attachedOutputs).
+     * Collects paths to all artifacts that will be considered for caching for the given project.
+     *
+     * <p>This includes:
+     * <ul>
+     *     <li>the main project artifact file (for example, the built JAR), if it has been produced, and</li>
+     *     <li>any attached output directories configured via {@code cacheConfig.getAttachedOutputs()} under the
+     *         project's target directory, when {@code cacheConfig.isCacheCompile()} is enabled.</li>
+     * </ul>
+     * Only paths that currently exist on disk are included in the returned set; non-existent files or directories
+     * are ignored.
+     *
+     * @param project the Maven project whose artifact and attached output paths should be collected
+     * @return a set of existing filesystem paths for the project's main artifact and configured attached outputs
      */
     private Set<Path> collectCachedArtifactPaths(MavenProject project) {
         Set<Path> paths = new HashSet<>();

src/test/java/org/apache/maven/buildcache/its/CacheCompileDisabledTest.java

@@ -62,8 +62,10 @@ void compileDoesNotCacheWhenDisabled(Verifier verifier) throws VerificationExcep
         verifier.verifyErrorFreeLog();
 
         // Verify NO cache entry was created (no buildinfo.xml in local cache)
-        boolean hasCacheEntry =
-                Files.walk(localCache).anyMatch(p -> p.getFileName().toString().equals("buildinfo.xml"));
+        boolean hasCacheEntry;
+        try (Stream<Path> walk = Files.walk(localCache)) {
+            hasCacheEntry = walk.anyMatch(p -> p.getFileName().toString().equals("buildinfo.xml"));
+        }
         assertFalse(hasCacheEntry, "Cache entry should NOT be created when maven.build.cache.cacheCompile=false");
 
         // Clean project and run compile again
@@ -103,8 +105,10 @@ void compileCreatesCacheEntryWhenEnabled(Verifier verifier) throws VerificationE
         verifier.verifyErrorFreeLog();
 
         // Verify cache entry WAS created
-        boolean hasCacheEntry =
-                Files.walk(localCache).anyMatch(p -> p.getFileName().toString().equals("buildinfo.xml"));
+        boolean hasCacheEntry;
+        try (Stream<Path> walk = Files.walk(localCache)) {
+            hasCacheEntry = walk.anyMatch(p -> p.getFileName().toString().equals("buildinfo.xml"));
+        }
         assertTrue(hasCacheEntry, "Cache entry should be created when maven.build.cache.cacheCompile=true (default)");
 
         // Clean project and run compile again