mirror of
https://github.com/unisonweb/unison.git
synced 2024-09-11 10:35:57 +03:00
This is for consistency with the `cmark` style. Now the blocks we still pretty-print ourselves will match the bulk of them that `cmark` produces.
160 lines
3.7 KiB
Markdown
160 lines
3.7 KiB
Markdown
# Documenting Unison code
|
|
|
|
Unison documentation is written in Unison. Documentation is a value of the following type:
|
|
|
|
``` ucm
|
|
scratch/main> view lib.builtins.Doc
|
|
|
|
type lib.builtins.Doc
|
|
= Blob Text
|
|
| Link Link
|
|
| Source Link
|
|
| Signature Term
|
|
| Evaluate Term
|
|
| Join [lib.builtins.Doc]
|
|
|
|
```
|
|
You can create these `Doc` values with ordinary code, or you can use the special syntax. A value of structural type `Doc` can be created via syntax like:
|
|
|
|
``` unison
|
|
doc1 = [: This is some documentation.
|
|
|
|
It can span multiple lines.
|
|
|
|
Can link to definitions like @List.drop or @List
|
|
|
|
:]
|
|
```
|
|
|
|
``` ucm
|
|
|
|
Loading changes detected in scratch.u.
|
|
|
|
I found and typechecked these definitions in scratch.u. If you
|
|
do an `add` or `update`, here's how your codebase would
|
|
change:
|
|
|
|
⍟ These new definitions are ok to `add`:
|
|
|
|
doc1 : Doc
|
|
|
|
```
|
|
Syntax:
|
|
|
|
`[:` starts a documentation block; `:]` finishes it. Within the block:
|
|
|
|
- Links to definitions are done with `@List`. `\@` (and `\:]`) if you want to escape.
|
|
- `@[signature] List.take` expands to the type signature of `List.take`
|
|
- `@[source] List.map` expands to the full source of `List.map`
|
|
- `@[include] someOtherDoc`, inserts a value `someOtherDoc : Doc` here.
|
|
- `@[evaluate] someDefinition` expands to the result of evaluating `someDefinition`, which must be a pre-existing definition in the codebase (can't be an arbitrary expression).
|
|
|
|
### An example
|
|
|
|
We are going to document `List.take` using some verbiage and a few examples. First we have to add the examples to the codebase:
|
|
|
|
``` unison
|
|
List.take.ex1 = take 0 [1,2,3,4,5]
|
|
List.take.ex2 = take 2 [1,2,3,4,5]
|
|
```
|
|
|
|
``` ucm
|
|
|
|
Loading changes detected in scratch.u.
|
|
|
|
I found and typechecked these definitions in scratch.u. If you
|
|
do an `add` or `update`, here's how your codebase would
|
|
change:
|
|
|
|
⍟ These new definitions are ok to `add`:
|
|
|
|
List.take.ex1 : [Nat]
|
|
List.take.ex2 : [Nat]
|
|
|
|
```
|
|
``` ucm
|
|
scratch/main> add
|
|
|
|
⍟ I've added these definitions:
|
|
|
|
List.take.ex1 : [Nat]
|
|
List.take.ex2 : [Nat]
|
|
|
|
```
|
|
And now let's write our docs and reference these examples:
|
|
|
|
``` unison
|
|
List.take.doc = [:
|
|
`@List.take n xs` returns the first `n` elements of `xs`. (No need to add line breaks manually. The display command will do wrapping of text for you. Indent any lines where you don't want it to do this.)
|
|
|
|
## Examples:
|
|
|
|
@[source] List.take.ex1
|
|
🔽
|
|
@List.take.ex1 = @[evaluate] List.take.ex1
|
|
|
|
|
|
@[source] List.take.ex2
|
|
🔽
|
|
@List.take.ex2 = @[evaluate] List.take.ex2
|
|
:]
|
|
```
|
|
|
|
``` ucm
|
|
|
|
Loading changes detected in scratch.u.
|
|
|
|
I found and typechecked these definitions in scratch.u. If you
|
|
do an `add` or `update`, here's how your codebase would
|
|
change:
|
|
|
|
⍟ These new definitions are ok to `add`:
|
|
|
|
List.take.doc : Doc
|
|
|
|
```
|
|
Let's add it to the codebase.
|
|
|
|
``` ucm
|
|
scratch/main> add
|
|
|
|
⍟ I've added these definitions:
|
|
|
|
List.take.doc : Doc
|
|
|
|
```
|
|
We can view it with `docs`, which shows the `Doc` value that is associated with a definition.
|
|
|
|
``` ucm
|
|
scratch/main> docs List.take
|
|
|
|
`List.take n xs` returns the first `n` elements of `xs`. (No
|
|
need to add line breaks manually. The display command will do
|
|
wrapping of text for you. Indent any lines where you don't
|
|
want it to do this.)
|
|
|
|
## Examples:
|
|
|
|
List.take.ex1 : [Nat]
|
|
List.take.ex1 = List.take 0 [1, 2, 3, 4, 5]
|
|
🔽
|
|
ex1 = []
|
|
|
|
|
|
List.take.ex2 : [Nat]
|
|
List.take.ex2 = List.take 2 [1, 2, 3, 4, 5]
|
|
🔽
|
|
ex2 = [1, 2]
|
|
|
|
|
|
```
|
|
Note that if we view the source of the documentation, the various references are *not* expanded.
|
|
|
|
``` ucm
|
|
scratch/main> view List.take
|
|
|
|
builtin lib.builtins.List.take :
|
|
lib.builtins.Nat -> [a] -> [a]
|
|
|
|
```
|