Various Enhancements

README.md

@@ -1,3 +1,12 @@
+### Notes about this fork
+
+- Focused on extracting structured data (EDN) from jars.
+- Any writing-related (HTML etc.) dependencies have been removed, code is kept to keep diff to mainline manageable.
+- Various tweaks have been done to align the results of Clojure and ClojureScript analysis.
+
+
+---
+
 # Codox
 
 A tool for generating API documentation from Clojure or ClojureScript

codox/deps.edn

@@ -0,0 +1,4 @@
+{:paths ["src" "resources" "test-sources"]
+ :deps {org.clojure/clojure {:mvn/version "1.9.0"}
+ org.clojure/tools.namespace {:mvn/version "0.2.11"}
+ org.clojure/clojurescript {:mvn/version "1.10.339"}}}

codox/src/codox/main.clj

@@ -2,8 +2,10 @@
  "Main namespace for generating documentation"
  (:use [codox.utils :only (add-source-paths)])
  (:require [clojure.string :as str]
+ [clojure.pprint]
  [clojure.java.shell :as shell]
  [codox.reader.clojure :as clj]
+ [codox.reader.clojurescript :as cljs]
  [codox.reader.plaintext :as text]))
 
 (defn- writer [{:keys [writer]}]
@@ -19,29 +21,9 @@
  (throw
  (Exception. (str "Could not resolve codox writer " writer-sym))))))
 
-(defn- macro? [var]
- (= (:type var) :macro))
-
-(defn- read-macro-namespaces [paths read-opts]
- (->> (clj/read-namespaces paths read-opts)
- (map (fn [ns] (update-in ns [:publics] #(filter macro? %))))
- (remove (comp empty? :publics))))
-
-(defn- merge-namespaces [namespaces]
- (for [[name namespaces] (group-by :name namespaces)]
- (assoc (first namespaces) :publics (mapcat :publics namespaces))))
-
-(defn- cljs-read-namespaces [paths read-opts]
- ;; require is here to allow Clojure 1.3 and 1.4 when not using ClojureScript
- (require 'codox.reader.clojurescript)
- (let [reader (find-var 'codox.reader.clojurescript/read-namespaces)]
- (merge-namespaces
- (concat (reader paths read-opts)
- (read-macro-namespaces paths read-opts)))))
-
 (def ^:private namespace-readers
  {:clojure clj/read-namespaces
- :clojurescript cljs-read-namespaces})
+ :clojurescript cljs/read-namespaces})
 
 (defn- var-symbol [namespace var]
  (symbol (name (:name namespace)) (name (:name var))))
@@ -125,3 +107,29 @@
  (write-fn (assoc options
  :namespaces namespaces
  :documents documents)))))
+
+(defn -main
+ "The main entry point for reading API information from files in a directory.
+
+ To analyze a project (debugging etc.) follow these steps:
+
+ 1. unzip the project's jar into a directory
+ 2. add the project's coordinates to the local `deps.edn` file
+ 3. add the jar contents directory to `:paths` in `deps.edn`
+
+ You can then call this main function as follows:
+
+ clj -m codox.main clojurescript jar-contents-dir/
+ clj -m codox.main clojure jar-contents-dir/"
+ [lang path]
+ (println "Analyzing lang:" lang)
+ (println "Analyzing path:" path)
+ (assert (#{"clojure" "clojurescript"} lang))
+ (->> (generate-docs {:writer 'clojure.core/identity
+ :source-paths [path]
+ :language (keyword lang)})
+ :namespaces
+ ;; Walk/realize entire structure, otherwise "Excluding ->Xyz"
+ ;; messages will be mixed with the pretty printed output
+ (clojure.walk/prewalk identity)
+ clojure.pprint/pprint))

codox/src/codox/reader/clojure.clj

@@ -116,8 +116,8 @@
 
 (defn- find-namespaces [file]
  (cond
- (.isDirectory file) (ns/find-namespaces-in-dir file)
- (jar-file? file) (ns/find-namespaces-in-jarfile (JarFile. file))))
+ (.isDirectory file) (set (ns/find-namespaces-in-dir file))
+ (jar-file? file) (set (ns/find-namespaces-in-jarfile (JarFile. file)))))
 
 (defn read-namespaces
  "Read Clojure namespaces from a set of source directories (defaults

codox/src/codox/reader/clojurescript.clj

@@ -4,6 +4,8 @@
  (:require [clojure.java.io :as io]
  [cljs.analyzer :as an]
  [cljs.analyzer.api :as ana]
+ [cljs.closure]
+ [cljs.env]
  [clojure.string :as str]))
 
 (defn- cljs-filename? [filename]
@@ -15,7 +17,7 @@
  (-> file .getName cljs-filename?)))
 
 (defn- remove-quote [x]
- (if (and (list? x) (= (first x) 'quote))
+ (if (and (seq? x) (= (first x) 'quote))
  (second x)
  x))
 
@@ -50,15 +52,16 @@
  :else :var))
 
 (defn- read-var [file vars var]
- (-> var
- (select-keys [:name :line :arglists :doc :dynamic :added :deprecated :doc/format])
- (update-some :name (comp symbol name))
- (update-some :arglists remove-quote)
- (update-some :doc correct-indent)
- (assoc-some :file (.getPath file)
- :type (var-type var)
- :members (map (partial read-var file vars)
- (protocol-methods var vars)))))
+ (let [vt (var-type var)]
+ (-> var
+ (select-keys [:name :line :arglists :doc :dynamic :added :deprecated :doc/format])
+ (update-some :name (comp symbol name))
+ (update-some :arglists remove-quote)
+ (update-some :doc correct-indent)
+ (assoc-some :file (if (= vt :macro) (:file var) (.getPath file))
+ :type vt
+ :members (map (partial read-var file vars)
+ (protocol-methods var vars))))))
 
 (defn- read-publics [state namespace file]
  (let [vars (vals (ana/ns-publics state namespace))]
@@ -70,10 +73,11 @@
  (sort-by (comp str/lower-case :name)))))
 
 (defn- analyze-file [file]
- (let [state (ana/empty-state)]
- (binding [an/*analyze-deps* false]
- (ana/no-warn
- (ana/analyze-file state file {})))
+ (let [opts (cljs.closure/add-implicit-options {})
+ state (cljs.env/default-compiler-env opts)]
+ (ana/no-warn
+ (cljs.closure/validate-opts opts)
+ (ana/analyze-file state file opts))
  state))
 
 (defn- read-file [path file exception-handler]

codox/test-sources/codox_test/macro.cljc

@@ -0,0 +1,18 @@
+(ns codox-test.macro)
+
+(defmacro test
+ [a b]
+ `(+ ~a ~b))
+
+(defmacro test2
+ [a & xs]
+ `(reduce + ~a ~(vec xs)))
+
+;; https://github.com/jarohen/nomad/blob/5520c332c5c6d5eef4dcb0930c735900d63dea2a/src/nomad/config.clj#L98-L111
+
+(defn with-config-override* [{:keys [switches secret-keys override-switches] :as opts-override} f]
+ nil)
+
+(doto (defmacro with-config-override [opts & body]
+ `(with-config-override* ~opts (fn [] ~@body)))
+ (alter-meta! assoc :arglists '([{:keys [switches secret-keys override-switches] :as opts-override} & body])))

codox/test-sources/codox_test/multimethod.cljc

@@ -0,0 +1,9 @@
+(ns codox-test.multimethod)
+
+(defmulti start (fn [k opts] k))
+
+(defmethod start :car [_ opts]
+ (println "Starting car..." opts))
+
+(defmethod start :helicopter [_ opts]
+ (println "Starting helicopter..." opts))

codox/test-sources/codox_test/record.cljc

@@ -0,0 +1,3 @@
+(ns codox-test.record)
+
+(defrecord CodoxSystem [components])

codox/test-sources/codox_test/spec.cljc

@@ -0,0 +1,4 @@
+(ns codox-test.spec
+ (:require [clojure.spec.test.alpha :as st]))
+
+(st/with-instrument-disabled (+ 1 2 3))

codox/test-sources/codox_test/spec_two.cljs

@@ -0,0 +1,4 @@
+(ns codox-test.spec-two
+ (:require [clojure.spec.test.alpha :as st]))
+
+(st/with-instrument-disabled (+ 1 2 3))