Add more documentation

Author: mbg

lib/analyze.js

@@ -11,7 +11,7 @@ import { getApiClient } from "./api-client";
 import { setupCppAutobuild } from "./autobuild";
 import { CodeQL, getCodeQL } from "./codeql";
 import * as configUtils from "./config-utils";
-import { getJavaDependencyDir } from "./dependency-caching";
+import { getJavaTempDependencyDir } from "./dependency-caching";
 import { addDiagnostic, makeDiagnostic } from "./diagnostics";
 import {
   DiffThunkRange,
@@ -168,9 +168,13 @@ export async function runExtraction(
           await setupCppAutobuild(codeql, logger);
         }
 
+        // The Java `build-mode: none` extractor places dependencies (.jar files) in the
+        // database scratch directory by default. For dependency caching purposes, we want
+        // a stable path that caches can be restored into and that we can cache at the
+        // end of the workflow (i.e. that does not get removed when the scratch directory is).
         if (language === Language.java && config.buildMode === BuildMode.None) {
           process.env["CODEQL_EXTRACTOR_JAVA_OPTION_BUILDLESS_DEPENDENCY_DIR"] =
-            getJavaDependencyDir();
+            getJavaTempDependencyDir();
         }
 
         await codeql.extractUsingBuildMode(config, language);

lib/analyze.js.map

@@ -29,7 +29,12 @@ interface CacheConfig {
 const CODEQL_DEPENDENCY_CACHE_PREFIX = "codeql-dependencies";
 const CODEQL_DEPENDENCY_CACHE_VERSION = 1;
 
-export function getJavaDependencyDir(): string {
+/**
+ * Returns a path to a directory intended to be used to store .jar files
+ * for the Java `build-mode: none` extractor.
+ * @returns The path to the directory that should be used by the `build-mode: none` extractor.
+ */
+export function getJavaTempDependencyDir(): string {
   return join(getTemporaryDirectory(), "codeql_java", "repository");
 }
 
@@ -44,7 +49,7 @@ const CODEQL_DEFAULT_CACHE_CONFIG: { [language: string]: CacheConfig } = {
       // Gradle
       join(os.homedir(), ".gradle", "caches"),
       // CodeQL Java build-mode: none
-      getJavaDependencyDir(),
+      getJavaTempDependencyDir(),
     ],
     hash: [
       // Maven