A bit of doc comments for our ClassPath implementation

Author: lrytz

src/compiler/scala/tools/nsc/util/ClassPath.scala

@@ -22,19 +22,43 @@ trait ClassPath {
   import scala.tools.nsc.classpath._
   def asURLs: Seq[URL]
 
-  /** Empty string represents root package */
+  /*
+   * These methods are mostly used in the ClassPath implementation to implement the `list` and
+   * `findX` methods below.
+   *
+   * However, there are some other uses in the compiler, to implement `invalidateClassPathEntries`,
+   * which is used by the repl's `:require` (and maybe the spark repl, https://github.com/scala/scala/pull/4051).
+   * Using these methods directly is more efficient than calling `list`.
+   *
+   * The `inPackage` string is a full package name, e.g. "" or "scala.collection".
+   */
+
   private[nsc] def hasPackage(pkg: String): Boolean
   private[nsc] def packages(inPackage: String): Seq[PackageEntry]
   private[nsc] def classes(inPackage: String): Seq[ClassFileEntry]
   private[nsc] def sources(inPackage: String): Seq[SourceFileEntry]
 
-  /** Allows to get entries for packages and classes merged with sources possibly in one pass. */
+  /**
+   * Returns packages and classes (source or classfile) that are members of `inPackage` (not
+   * recursively). The `inPackage` string is a full package name, e.g., "scala.collection".
+   *
+   * This is the main method uses to find classes, see class `PackageLoader`. The
+   * `rootMirror.rootLoader` is created with `inPackage = ""`.
+   */
   private[nsc] def list(inPackage: String): ClassPathEntries
 
   /**
-    * It returns both classes from class file and source files (as our base ClassRepresentation).
-    * So note that it's not so strictly related to findClassFile.
-    */
+   * Returns the class file and / or source file for a given external name, e.g., "java.lang.String".
+   * If there is both a class file and source file, the compiler can decide whether to read the
+   * class file or compile the source file.
+   *
+   * Internally this seems to be used only by `ScriptRunner`, but only to call `.isDefined`. That
+   * could probably be implemented differently.
+   *
+   * Externally, it is used by sbt's compiler interface:
+   * https://github.com/sbt/sbt/blob/v0.13.15/compile/interface/src/main/scala/xsbt/CompilerInterface.scala#L249
+   * Jason has some improvements for that in the works (https://github.com/scala/bug/issues/10289#issuecomment-310022699)
+   */
   def findClass(className: String): Option[ClassRepresentation] = {
     // A default implementation which should be overridden, if we can create the more efficient
     // solution for a given type of ClassPath
@@ -45,6 +69,16 @@ trait ClassPath {
 
     foundClassFromClassFiles orElse findClassInSources
   }
+
+  /**
+   * Returns the classfile for an external name, e.g., "java.lang.String". This method does not
+   * return source files.
+   *
+   * This method is used by the classfile parser. When parsing a Java class, its own inner classes
+   * are entered with a `ClassfileLoader` that parses the classfile returned by this method.
+   * It is also used in the backend, by the inliner, to obtain the bytecode when inlining from the
+   * classpath. It's also used by scalap.
+   */
   def findClassFile(className: String): Option[AbstractFile]
 
   def asClassPathStrings: Seq[String]