Event handler documentation

[gacelita]

At the moment, re-frame does not give users a way of adding docstrings to event handlers. I open this issue to discuss this possibility. Adding specs could be useful too (I'm fond of data specs)

Quick proof of concept for adding documentation, which extends reg-event-fx (ignores interceptors though)

(defonce ^:private extended-event-handler-data (atom {}))

(defn reg-event-fx
  ([kw f]
   (rf/reg-event-fx kw f))
  ([kw options f]
   (swap! extended-event-handler-data assoc kw options)
   (rf/reg-event-fx kw f)))

(defn event-handler-doc [kw]
  (:doc (get @extended-event-handler-data kw)))

(reg-event-fx
 ::categories.list
 {:doc "Lists categories indeed"}
 (fn [_ _]
   {:dispatch ["..."]}))

;;
;;

(event-handler-doc ::categories.list)
=> "Lists categories indeed"

[mike-thompson-day8]

Thanks. I'm working on a plan. More soon.

[ghost]

Why does a string after the keyword not work here, like it does for function definitions?

[celwell]

Until some kind of docstringability is added to re-frame, what would the suggested best practice be for clarifying quirky events? Comments above the reg-event-fx?

[gacelita]

Until some kind of docstringability is added to re-frame, what would the suggested best practice be for clarifying quirky events? Comments above the reg-event-fx?

Either that, or extracting the complex functionality (or all the functionality) to a function, and document the function