-
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 used in place of the title/reflink text and contains some part of the syntax and a name.
The usage section is a place to show what the syntax looks like more fully.
===== Name
syntax/js-literal
===== Display
#js literal
===== Usage
#js {...}
#js [...]
A description or usage example can link to other var entries using the names
discussed in the previous section, but with the doc: prefix. This is implemented as a standard github markdown link label. We append the markdown text with correct [doc:cljs.core/foo]:<...> URLs when processing them.
| markdown link | description |
|---|---|
[doc:cljs.core/foo] |
inline link, auto-named |
[custom name][doc:cljs.core/foo] |
inline link |
The related and moved sections use the same type of names discussed in the previous section, but without the doc: prefix:
===== Related cljs.core/foo syntax/js-literal special/try specialrepl/in-ns ===== Moved cljs.core/bar
Referencing namespaces is a little trickier, because we have a page for each API type (compiler or library), since they have different APIs.
library/cljs.repl <--- ns in the library API
compiler/cljs.repl <--- ns in the compiler API
The syntax page is its own thing which requires no prefix:
syntax <--- syntax forms
The special forms namespaces are also in the library API for consistency even though there aren't compiler API versions for them:
library/special <--- special forms ns
library/specialrepl <--- special forms REPL ns
Vars such as cljs.core/foo don't require an API type prefix like
library/cljs.core/foo because we are (safely I hope) assuming that symbols
of the same name between APIs have the same usages.
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.