[#103] Add some notes about the JDK sources

Author: bbatsov

src/orchard/java.clj

@@ -32,6 +32,16 @@
 ;; these, we search the JDK directory and add the source classpath entry
 ;; manually, if available. Prior to JDK9, parsing source files also requires
 ;; having `tools.jar` on the classpath, which we'll have to add as well.
+;;
+;; The context classloader may be different at startup and in a
+;; REPL (e.g. nREPL) session, and these classloaders may not share a modifiable
+;; ancestor classloader. That's why the current implementation checks that the
+;; JDK sources are visible on the classpath prior to invoking the Java parser,
+;; and if not, adds a classpath entry for them. (see `ensure-jdk-sources`)
+;;
+;; An alternative approach would be to pass the REPL's classloader to Orchard's
+;; functions that modify the classpath. You can find a more extensive discussion
+;; on that topic here https://github.com/clojure-emacs/orchard/issues/103.
 
 (defn jdk-find
   "Search common JDK path configurations for a specified file name and return a