Document JavaParser.Builder classpath options (#5926)

* Document `JavaParser.Builder` classpath options

* Update reference specifically for builder methods

* Mark `classpath(byte[]... classpath)` as deprecated

* Apply suggestions from code review

Co-authored-by: Jacob van Lingen <[email protected]>

---------

Co-authored-by: Jacob van Lingen <[email protected]>

Author: timtebeek

rewrite-java/src/main/java/org/openrewrite/java/JavaParser.java

@@ -19,6 +19,7 @@
 import org.intellij.lang.annotations.Language;
 import org.jspecify.annotations.Nullable;
 import org.openrewrite.*;
+import org.openrewrite.internal.ToBeRemoved;
 import org.openrewrite.java.internal.JavaTypeCache;
 import org.openrewrite.java.internal.parser.JavaParserClasspathLoader;
 import org.openrewrite.java.internal.parser.RewriteClasspathJarClasspathLoader;
@@ -111,6 +112,15 @@ static List<Path> filterArtifacts(String artifactName, List<Path> runtimeClasspa
         return artifacts;
     }
 
+    /**
+     * Load artifacts from packaged resources. This is useful for loading dependencies which are not on the recipe
+     * execution classpath, or where you need to load multiple different versions of the same artifact.
+     * Supports both {@link TypeTable} `classpath.tsv.gz` and packaged resource jars in `META-INF/rewrite/classpath/`.
+     *
+     * @param ctx                       The execution context to use for loading resources.
+     * @param artifactNamesWithVersions artifact prefix to match, e.g. "guava" or "guava-31" for a specific version.
+     * @return A list of paths to the located artifacts.
+     */
     static List<Path> dependenciesFromResources(ExecutionContext ctx, String... artifactNamesWithVersions) {
         if (artifactNamesWithVersions.length == 0) {
             return emptyList();
@@ -304,19 +314,43 @@ public B addClasspathEntry(Path entry) {
             return (B) this;
         }
 
+        /**
+         * Sets the classpath from runtime classpath dependencies of the process constructing the parser. Predates
+         * {@link #classpathFromResources(ExecutionContext, String...)}, with the latter preferred to limit dependencies
+         * needed on the recipe runtime classpath, as the runtime classpath may differ in say the CLI or Platform.
+         * <p>
+         * This is suitable, for example, when writing tests that may require older versions of dependencies,
+         * without needing to add them to the recipe runtime classpath through resources.
+         *
+         * @return A list of paths to jars on the runtime classpath of the process constructing the parser.
+         */
         public B classpath(String... artifactNames) {
             this.artifactNames = Arrays.asList(artifactNames);
             this.classpath = emptyList();
             return (B) this;
         }
 
+        /**
+         * Load artifacts from packaged resources. This is useful for loading dependencies which are not on the recipe
+         * execution classpath, or where you need to load multiple different versions of the same artifact.
+         * Supports both {@link TypeTable} `classpath.tsv.gz` and packaged resource jars in `META-INF/rewrite/classpath/`.
+         *
+         * @param ctx       The execution context to use for loading resources.
+         * @param classpath artifact prefix to match, e.g. "guava" or "guava-31" for a specific version.
+         * @return A list of paths to the located artifacts.
+         */
         @SuppressWarnings({"UnusedReturnValue", "unused"})
         public B classpathFromResources(ExecutionContext ctx, String... classpath) {
             this.artifactNames = emptyList();
             this.classpath = dependenciesFromResources(ctx, classpath);
             return (B) this;
         }
 
+        /**
+         * @deprecated prefer {@link #classpath} and {@link #classpathFromResources(ExecutionContext, String...)}.
+         */
+        @Deprecated
+        @ToBeRemoved(after = "2025-12-31", reason = "Use classpath or classpathFromResources instead.")
         public B classpath(byte[]... classpath) {
             this.classBytesClasspath = Arrays.asList(classpath);
             return (B) this;