Docstrings not available for some re-frame.core functions

[rads]

The re-frame.core namespace includes this comment:

;; So, we promote a `defn` in a deeper namespace "up" to the API
;; via a `def` in this namespace.
;;
;; Turns out, this approach makes it hard:
;;   - to auto-generate API docs
;;   - for IDEs to provide code completion on functions in the API

As a Cursive user I see that the docstring is parsed using static analysis on the Clojure code. This means there's no way to copy the docstring from another function without changing how Cursive currently works.

This forces libraries to make a decision: do we put the docstring on the inner function or the outer one? Re-frame currently keeps the docstring on the inner function. Unfortunately that results in a developer experience like this:

This is confusing and inconvenient for the most common use case. I suggest that we move the docstring to the outer function to allow the docstring to show up as it should:

We can replace the docstring of the inner function with instructions to find the canonical docstring:

I work with many people who are just getting started with Re-frame. For beginners the docstrings are a vital part of the development experience. In exchange for a little internal ugliness we can optimize for the most common use case and improve the usability of the library for everyone.

[danielcompton]

See also #257 and cursive-ide/cursive#1073.

Edit: not that Cursive issue, cursive-ide/cursive#944 as Colin notes below is the right one.

[cursive-ide]

The relevant Cursive issue is cursive-ide/cursive#944. I'll see if I can address this on the Cursive side soon, since this is a common issue with several popular libraries.

[superstructor]

Duplicate of #216. Both are now fixed. See comment in that issue.