Create API documentation for core.cljs

[mike-thompson-day8]

The API for re-frame has grown to the point that there should be docs. That means docs for the functions exposed in re-frame.core

• decide which tool to use - codox ?
• where to put the docs?
• review all docstrings for clarity and completeness.
• historically, core.cljs used def to promote functions deeper in the implementation up to the API level. These defs don't have docstrings. What to do about this?

That final point describes this practice within core.cljs:

(def some-thing  re-frame.impl/some-thing)

[danielcompton]

Relates to #62.

[mike-thompson-day8]

See also #257

[agzam]

As a newbie to re-frame this baffles me a bit. Why there's no unified api docs wiki or whatever? Or everything is really so simple - after you learn the basics, you won't need documentation to any of re-frame.core functions?

[mike-thompson-day8]

Revising this issue after a long absence.

A good-enough version of API docs can be found here: https://github.com/Day8/re-frame/blob/master/docs/API.md

I won't close because eventually we'd still like a better solution.

[superstructor]

Any solution must deliver the following two outcomes:

• API documentation generation (e.g. codox, cljdoc etc)-
• Common IDEs code assist features (e.g IntelliJ/Cursive, Emacs, Calva etc)

I investigated 3 options

1. using a macro - like “defvar” proposed in PR Add docstrings to vars in re-frame.core #257
2. move the relevant functions in their entirety to re-frame.core
3. create wrapper functions with the docstring and args that delegate to the other namespaces thanks to suggestion by @mike-thompson-day8

Tools such as IntelliJ/Cursive and Joker perform static analysis of code which rules out any macro-based approach.

Moving the entire function implementation is undesirable from a code organisation and style perspective.

Therefore we decided to go with creating wrapper functions with the docstrings and args in re-frame.core.