cljsdoc files

The ClojureScript API Docs Builder auto-generates a lot of API information, but we want to supplement that data with markdown descriptions, usage examples, and related symbols.

To this end, we use simple plaintext cljsdoc files, namely one for every symbol. This allows us to track their changes with Git and to simplify contributions with Pull Requests.

As an example, here is the cljsdoc file for cljs.core/assoc-in:

===== Name
cljs.core/assoc-in

===== Signature
[m [k & ks] v]

===== Description

Associates a value in a nested associative structure, where `ks` is a sequence
of keys and `v` is the new value. Returns a new nested structure.

If any levels do not exist, hash-maps will be created.

===== Related
cljs.core/assoc
cljs.core/update-in
cljs.core/get-in

===== Example#e76f20

```clj
(def users [{:name "James" :age 26}
            {:name "John" :age 43}])
```

Update the age of the second (index 1) user:

```clj
(assoc-in users [1 :age] 44)
;;=> [{:name "James", :age 26}
;;    {:name "John", :age 44}]
```

Insert the password of the second (index 1) user:

```clj
(assoc-in users [1 :password] "nhoJ")
;;=> [{:name "James", :age 26}
;;    {:password "nhoJ", :name "John", :age 43}]
```

Lines starting with ===== are section delimiters. The title of the section follows the equal signs. All lines following the section title (up to the next section line) belong to that section.

Section	Description
===== Name	the fully-qualified symbol name
===== Description	markdown-formatted description of the symbol
===== Signature	allows renaming function parameters (vector per line)
===== Related	list of related fully-qualified symbols (one per line)
===== Example	markdown-formatted example

Examples

Example titles should have a hash like ===== Example#e76f20. This is done to create unique persisting anchor links to them. Generate example hash here

Here's an Examples Guide to help us write consistent examples.

Checking Errors

The cljsdoc compiler will catch most of the mistakes that you can make, like misspelling sections or referring to non-existent ClojureScript symbols. Also, if it detects new symbols that do not have cljsdoc files, it will create stub files for them.

$ lein run

This will take 5-10 minutes to compile the first time. Subsequent runs take ~10s.

Previewing

You can preview the reference page for the symbol by installing Grip and running from the project root:

$ grip catalog
 * Running on http://localhost:5000/ (Press CTRL+C to quit)

Then navigate to your symbol's reference page to see your changes.

Contribution Workflow

⚡	All symbol pages have a link to its _cljsdoc_ file at the bottom of its page for easier contribution.

If you want to see only symbols with unfinished cljsdoc files, follow this:

1. Check UNFINISHED.md for symbols that are missing sections.
2. Click ref column for the full reference preview, and click cljsdoc column to edit the cljsdoc.

Different versions?

There is currently no facility for applying cljsdoc files for different versions of an API symbol.

If this becomes a problem, we can either:

• append version suffixes to cljsdoc filenames, which will be used from that version up to the next version with a matching cljsdoc version suffix.
• we can apply a similar scheme on a section-by-section basis by appending section titles with version in parentheses.