CLJS-1118: cljs.repl/doc support for protocols

Author: swannodette

src/clj/cljs/core.clj

@@ -1234,14 +1234,20 @@
   => 17"
   [psym & doc+methods]
   (let [p (:name (cljs.analyzer/resolve-var (dissoc &env :locals) psym))
-        psym (vary-meta psym assoc :protocol-symbol true)
+        [doc methods] (if (core/string? (first doc+methods))
+                        [(first doc+methods) (next doc+methods)]
+                        [nil doc+methods])
+        psym (vary-meta psym assoc
+               :doc doc
+               :protocol-symbol true)
         ns-name (-> &env :ns :name)
         fqn (fn [n] (symbol (core/str ns-name "." n)))
         prefix (protocol-prefix p)
-        methods (if (core/string? (first doc+methods)) (next doc+methods) doc+methods)
         _ (core/doseq [[mname & arities] methods]
             (when (some #{0} (map count (filter vector? arities)))
-              (throw (Exception. (core/str "Invalid protocol, " psym " defines method " mname " with arity 0")))))
+              (throw (Exception.
+                       (core/str "Invalid protocol, " psym
+                                 " defines method " mname " with arity 0")))))
         expand-sig (fn [fname slot sig]
                      `(~sig
                        (if (and ~(first sig) (. ~(first sig) ~(symbol (core/str "-" slot)))) ;; Property access needed here.
@@ -1257,18 +1263,26 @@
                  (into {}
                    (map
                      (fn [[fname & sigs]]
-                       (let [sigs (take-while vector? sigs)]
-                         [fname (vec sigs)]))
+                       (let [doc (as-> (last sigs) doc
+                                   (when (core/string? doc) doc))
+                             sigs (take-while vector? sigs)]
+                         [(vary-meta fname assoc :doc doc)
+                          (vec sigs)]))
                      methods)))
         method (fn [[fname & sigs]]
-                 (let [sigs (take-while vector? sigs)
+                 (let [doc (as-> (last sigs) doc
+                             (when (core/string? doc) doc))
+                       sigs (take-while vector? sigs)
                        slot (symbol (core/str prefix (name fname)))
-                       fname (vary-meta fname assoc :protocol p)]
-                   `(defn ~fname ~@(map (fn [sig]
-                                          (expand-sig fname
-                                                      (symbol (core/str slot "$arity$" (count sig)))
-                                                      sig))
-                                        sigs))))]
+                       fname (vary-meta fname assoc
+                               :protocol p
+                               :doc doc)]
+                   `(defn ~fname
+                      ~@(map (fn [sig]
+                               (expand-sig fname
+                                 (symbol (core/str slot "$arity$" (count sig)))
+                                 sig))
+                          sigs))))]
     `(do
        (set! ~'*unchecked-if* true)
        (def ~psym (js-obj))

src/clj/cljs/repl.clj

@@ -986,10 +986,20 @@ itself (not its value) is returned. The reader macro #'x expands to (var x)."}})
 
               (ana-api/resolve &env name)
               `(cljs.repl/print-doc
-                 (quote ~(update-in
-                           (select-keys (ana-api/resolve &env name)
-                             [:ns :name :doc :forms :arglists :macro :url])
-                           [:name] clojure.core/name)))))))))
+                 (quote ~(let [var (ana-api/resolve &env name)
+                               m (select-keys var
+                                   [:ns :name :doc :forms :arglists :macro :url])]
+                           (cond-> (update-in m [:name] clojure.core/name)
+                             (:protocol-symbol var)
+                             (assoc :protocol true
+                                    :methods
+                                    (->> (get-in var [:protocol-info :methods])
+                                      (map (fn [[fname sigs]]
+                                             [fname {:doc (:doc
+                                                            (ana-api/resolve &env
+                                                              (symbol (str (:ns var)) (str fname))))
+                                                     :arglists (seq sigs)}]))
+                                      (into {})))))))))))))
 
 (defmacro find-doc
   "Prints documentation for any var whose documentation or name

src/cljs/cljs/repl.cljs

@@ -12,6 +12,8 @@
 (defn print-doc [m]
   (println "-------------------------")
   (println (str (when-let [ns (:ns m)] (str ns "/")) (:name m)))
+  (when (:protocol m)
+    (println "Protocol"))
   (cond
     (:forms m) (doseq [f (:forms m)]
                  (println "  " f))
@@ -33,4 +35,11 @@
         (println "Macro"))
       (when (:repl-special-function m)
         (println "REPL Special Function"))
-      (println " " (:doc m)))))
+      (println " " (:doc m))
+      (when (:protocol m)
+        (doseq [[name {:keys [doc arglists]}] (:methods m)]
+          (println)
+          (println " " name)
+          (println " " arglists)
+          (when doc
+            (println " " doc)))))))