-
Notifications
You must be signed in to change notification settings - Fork 23
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.
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 |
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.
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.
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.
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.
| ⚡ | 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:
- Check UNFINISHED.md for symbols that are missing sections.
- Click ref column for the full reference preview, and click cljsdoc column to edit the cljsdoc.