cljsdoc files

Every API or Syntax entry has an associated cljsdoc file to allow simple Pull Requests. This wiki page describes its format.

The cljsdoc file is plaintext. Its purpose is to hold supplementary information like a markdown-formatted description, usage examples, and a list of related symbols. The docs builder uses this file to supplement the auto-parsed information like history, source code, signature, etc.

For example, below is the cljsdoc file for cljs.core/assoc-in, rendered to its final page here.

===== 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
===== Moved	if moved to a new symbol, the fully-qualified symbol name

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.

Versioning

If some attributes only apply after certain versions, include the version in parentheses after the title.

Moved requires a version to know when it was moved.

===== Moved (0.0-3211)
cljs.core/foo

Description can be updated at some version.

===== Description (0.0-3211)
This symbol was removed because <reason>.  Use <alternative> instead.

NOTE: this versioning option is only implemented to capture small change deltas (i.e. renames and removals). We don't anticipate many different versions of each section to start flooding each file. It it does, we'll separate changes into separate files.

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.