-
Notifications
You must be signed in to change notification settings - Fork 23
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 (possibly fake) |
===== Display |
a display name (required for syntax forms) |
===== Description |
markdown-formatted description of the symbol |
===== Signature |
allows renaming function parameters (vector per line) |
===== Usage |
usage strings (for syntax forms) (one 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 |
The name section is straightforward for most symbols like cljs.core/assoc-in,
which is a real namespace-qualified symbol.
Special forms do not have a namespace but are named as if they existed in a special/
or specialrepl/ namespace. This is never seen by the user, but is used behind the
scenes for consistency.
Likewise, syntax forms are named under a syntax/ namespace.
A unique symbol name is given to each form for identification. The display name
is the only one seen by the user.
===== Name
syntax/js-literal
===== Display
#js literal
===== Usage
#js {...}
#js [...]
A description or usage example can link to other cljsdoc entries using the names discussed in the previous section. This is through standard github markdown rules, using the entry name as a link:
| markdown link | description |
|---|---|
[cljs.core/foo] |
inline link, auto-named |
[custom name](cljs.core/foo) |
inline link |
[custom name]:cljs.core/foo |
ref link, replacing all refs to [custom name]
|
The related section is just a list of the same type of names discussed in the previous section:
===== Related cljs.core/foo syntax/js-literal special/try specialrepl/in-ns
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.