Add optional docstring to defui, behavior, and object.

Falls back to :desc if :doc is not available.

src/lt/macros.clj

@@ -12,7 +12,8 @@
   * :reaction (required) - Function to invoke when behavior is called.
                            First arg is object behavior is attached to
   * :triggers (required) - Set of keyword triggers that trigger behavior
-  * :desc - Brief description of behavior
+  * :desc - Brief description of behavior.
+  * :doc - Equivalent to a traditional function docstring.
   * :type - When set to :user, shows up in hints. Not enabled by default
   * :params - Vector of maps describing behavior args. Each map contains required :label key
               and optional keys of :type (:string, :number or :list), :items and :example
@@ -22,19 +23,25 @@
   (if (and (seq? reaction) (= 'fn (first reaction)))
     (let [[_ args & body] reaction]
       `(do
-         (defn- ~(namify "BEH" name) ~args ~@body)
+         (defn- ~(namify "BEH" name) ~(:doc r "") ~args ~@body)
          (lt.object/behavior* ~name ~@(apply concat (assoc r :reaction (namify "BEH" name))))))
     `(lt.object/behavior* ~name ~@(apply concat r))))
 
 (defmacro defui
   "Define a UI element for given hiccup data and key-value pairs
-  of events for element"
-  [sym params hiccup & events]
-  `(defn ~sym ~params
-     (let [e# (crate.core/html ~hiccup)]
-       (doseq [[ev# func#] (partition 2 ~(vec events))]
-         (lt.util.dom/on e# ev# func#))
-       e#)))
+  of events for element. Like defn, a docstring is optional."
+  [sym & decl]
+   (let [doc (if (string? (first decl))
+                  (first decl)
+                  "")
+        [params hiccup & events] (if (string? (first decl))
+                (next decl)
+                decl)]
+   `(defn ~sym ~doc ~params
+      (let [e# (crate.core/html ~hiccup)]
+        (doseq [[ev# func#] (partition 2 ~(vec events))]
+          (lt.util.dom/on e# ev# func#))
+        e#))))
 
 (defmacro ^:private timed [ev & body]
   `(let [start# (lighttable.util.js/now)

src/lt/object.cljs

@@ -226,7 +226,8 @@
   * :triggers - Set of object's triggers
   * :init - Init fn called when object is created. Fn's return value
             is hiccup html content and saved to :content
-  * :listeners (internal) - Map of triggers to vectors of behaviors"
+  * :listeners (internal) - Map of triggers to vectors of behaviors
+  * :doc - Equivalent to a traditional function docstring."
   [name & r]
   (-> (apply make-object* name r)
       (store-object*)

src/lt/plugins/doc.cljs

@@ -76,12 +76,46 @@
               (not= (:doc doc) "nil"))
      [:pre (:doc doc)])])
 
+(defn- retrieve-behavior
+  "Helper method for behavior `editor.doc.show!` to determine if the given `ns` and `name`
+  match existing behaviors.
+
+  Returns found behavior or `nil`."
+  [ns name]
+  (@object/behaviors (keyword (str ns "/" (subs name 2)))))
+
+(defn- retrieve-object-def
+  "Helper method for behavior `editor.doc.show!` to determine if the given `ns` and `name`
+  match existing object defs. Not recommended to print whole object def... use destructuring.
+
+  Returns found object def or `nil`."
+  [ns name]
+  (@object/object-defs (keyword (str ns "/" (subs name 2)))))
+
+(defn- retrieve-docstring
+  "Helper method for behavior `editor.doc.show!` that returns the docstring for a matching
+  object or behavior. If `:doc` is not found, then `:desc` is used. Otherwise `nil`."
+  [ns name]
+  (let [beh (retrieve-behavior ns name)
+        beh-doc (or (:doc beh) (:desc beh))
+        obj (retrieve-object-def ns name)
+        obj-doc (or (:doc obj) (:desc obj))]
+    (if (and (nil? beh-doc) (nil? obj-doc))
+      nil
+      (if (nil? beh-doc)
+        obj-doc
+        beh-doc))))
+
 (behavior ::editor.doc.show!
           :triggers #{:editor.doc.show!}
           :reaction (fn [editor doc]
                       (when (not= (:name doc) "")
-                        (inline-doc editor (doc-ui doc) {} (:loc doc)))
-                      ))
+                        ;; If :file and :doc are nil then this is likely a behavior or object.
+                        ;; Check if a match exists and splice the resulting :doc into the doc argument.
+                        (let [doc (if (and (nil? (:file doc)) (nil? (:doc doc)))
+                                    (merge doc {:doc (retrieve-docstring (:ns doc) (:name doc))})
+                                    doc)]
+                          (inline-doc editor (doc-ui doc) {} (:loc doc))))))
 
 (defui search-item [item]
   [:li