Integrate see-also straight into var metadata

Author: bbatsov

resources/see-also.edn

@@ -66,16 +66,25 @@
   (.delete (io/file cache-file-name))
   (reset! cache {}))
 
+(defn get-doc
+  "Get data for `var-name`.
+  If `export-edn-url` is omitted, `default-edn-file-url` is used."
+  {:added "0.5.0"}
+  ([var-name]
+   (get-doc var-name default-edn-file-url))
+  ([var-name export-edn-url]
+   (load-cache! export-edn-url)
+   (get @cache (keyword var-name))))
+
 (defn find-doc
-  "Find a document matching to ns-name and var-name from cached documents.
+  "Find a document matching `ns` and `sym` from cached documents.
   Cache will be updated when there are no cached documents or cached documents are old.
 
   If `export-edn-url` is omitted, `default-edn-file-url` is used.
 
   Return nil if there is no matching document."
   {:added "0.5.0"}
-  ([ns-name var-name]
-   (find-doc ns-name var-name default-edn-file-url))
-  ([ns-name var-name export-edn-url]
-   (load-cache! export-edn-url)
-   (get @cache (keyword ns-name var-name))))
+  ([ns sym]
+   (find-doc ns sym default-edn-file-url))
+  ([ns sym export-edn-url]
+   (get-doc (keyword ns sym) export-edn-url)))

src/orchard/clojuredocs.clj

@@ -140,24 +140,6 @@
      (some->> (cljs-meta/scoped-macro-meta env sym 'cljs.core)
               (cljs-meta/normalize-macro-meta)))))
 
-(def see-also-data
-  (edn/read-string (slurp (io/resource "see-also.edn"))))
-
-(defn see-also*
-  [{:keys [dialect unqualified-sym] :as m}]
-  (when-not (= :cljs dialect)
-    (some->> unqualified-sym
-             (str)
-             (symbol "clojure.core")
-             (str)
-             (get see-also-data)
-             (mapv symbol)
-             (filter resolve))))
-
-(def ^{:doc "Augment the map with see-also information. We have to use the
-resolved (real) namespace and name here"}
-  see-also (memoize see-also*))
-
 (defn info*
   "Provide the info map for the input ns and sym.
 
@@ -176,9 +158,6 @@ resolved (real) namespace and name here"}
     (some->
      meta
 
-     (merge (when-let [m (see-also params)]
-              {:see-also m}))
-
      (merge (when-let [file-path (:file meta)]
               {:file (cond-> file-path
                        (misc/boot-project?) cp/classpath-file-relative-path)})))))

src/orchard/info.clj

@@ -5,6 +5,7 @@
    [clojure.pprint :as pprint]
    [clojure.string :as str]
    [clojure.walk :as walk]
+   [orchard.clojuredocs :as cljdocs]
    [orchard.namespace :as ns]
    [orchard.misc :as misc]
    [orchard.spec :as spec]
@@ -69,6 +70,13 @@
         (assoc :file (some-> (ns/canonical-source ns) .getPath)))
     meta-map))
 
+(defn- maybe-add-see-also
+  "If the var `v` has a see-also has associated with it, assoc that into meta-map."
+  [v meta-map]
+  (if-let [see-also (:see-alsos (cljdocs/get-doc (var-name v)))]
+    (merge meta-map {:see-also see-also})
+    meta-map))
+
 (defn- maybe-protocol
   [info]
   (if-let [prot-meta (meta (:protocol info))]
@@ -82,6 +90,8 @@
     nil))
 
 (defn resolve-var
+  "Resolve `ns` and `sym` to a var.
+  The function is a simple wrapper around `clojure.core/ns-resolve`."
   [ns sym]
   {:pre [(symbol? ns) (symbol? sym)]}
   (if-let [ns (find-ns ns)]
@@ -94,6 +104,8 @@
            nil))))
 
 (defn resolve-aliases
+  "Retrieve the ns aliases for `ns`.
+  The function is a simple wrapper around `clojure.core/ns-alias`."
   [ns]
   {:pre [(symbol? ns)]}
   (when-let [ns (find-ns ns)]
@@ -159,7 +171,8 @@
                         maybe-add-file
                         maybe-add-url
                         (update :ns ns-name))]
-       (maybe-add-spec v meta-map)))))
+       (maybe-add-spec v meta-map)
+       (maybe-add-see-also v meta-map)))))
 
 (defn meta+
   "Return special form or var's meta."

src/orchard/meta.clj

@@ -390,28 +390,20 @@
 ;;;;;;;;;;;;;;;;;;
 
 (deftest see-also-test
-  (let [expected '(clojure.core/map-indexed
-                   clojure.core/pmap
-                   clojure.core/amap
-                   clojure.core/mapcat
-                   clojure.core/keep
-                   clojure.core/juxt
-                   clojure.core/mapv
-                   clojure.core/reduce
-                   clojure.core/run!)]
-
-    (testing "unit test of info/see-also"
-      (is (= expected (-> '{:ns orchard.test-ns :sym map}
-                          info/normalize-params
-                          info/see-also))))
+  (let [expected [:clojure.core/map-indexed
+                  :clojure.core/pmap
+                  :clojure.core/amap
+                  :clojure.core/mapcat
+                  :clojure.core/keep
+                  :clojure.core/juxt
+                  :clojure.core/mapv
+                  :clojure.core/reduce
+                  :clojure.core/run!]]
 
     (testing "info/see-also through info/info* in a required namespace"
       (is (= expected (-> '{:ns orchard.test-ns :sym map}
                           info/info*
-                          :see-also)))))
-
-  (testing "info/see-also does not support ClojureScript"
-    (is (nil? (:see-also (info/info* '{:ns cljs.core :sym map :dialect :cljs :env {}}))))))
+                          :see-also))))))
 
 (deftest info-jvm-test
   (is (info/info* {:ns 'orchard.info :sym 'java.lang.Class}))

test/orchard/info_test.clj

@@ -1,6 +1,5 @@
 (ns orchard.java.resource-test
   (:require
-   [clojure.string :as str]
    [clojure.test :refer [deftest is testing]]
    [orchard.java.resource :as resource]))
 
@@ -9,7 +8,6 @@
 
 (deftest project-resources-test
   (testing "get the correct resources for the orchard project"
-    (let [resources (->> (resource/project-resources)
-                         (remove #(str/ends-with? (.getAbsolutePath (:root %)) "test-resources")))]
-      (is (= "see-also.edn" (-> resources first :relpath)))
+    (let [resources (resource/project-resources)]
+      (is (= "clojuredocs/export.edn" (-> resources first :relpath)))
       (is (= java.net.URL (-> resources first :url class))))))