2019-11-05 02:00:25 +03:00
# Documenting Unison code
Unison documentation is written in Unison. Documentation is a value of the following type:
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-26 03:30:45 +03:00
scratch/main> view lib.builtins.Doc
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
type lib.builtins.Doc
= Blob Text
| Link Link
| Source Link
| Signature Term
| Evaluate Term
| Join [lib.builtins.Doc]
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
```
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:
2024-07-10 17:46:18 +03:00
``` unison
2024-06-26 03:30:45 +03:00
doc1 = [: This is some documentation.
It can span multiple lines.
Can link to definitions like @List .drop or @List
:]
```
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-26 03:30:45 +03:00
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:
2024-07-10 17:46:18 +03:00
- 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).
2024-06-26 03:30:45 +03:00
### 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:
2024-07-10 17:46:18 +03:00
``` unison
2024-06-26 03:30:45 +03:00
List.take.ex1 = take 0 [1,2,3,4,5]
List.take.ex2 = take 2 [1,2,3,4,5]
```
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-26 03:30:45 +03:00
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]
```
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-26 03:30:45 +03:00
scratch/main> add
⍟ I've added these definitions:
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
List.take.ex1 : [Nat]
List.take.ex2 : [Nat]
```
And now let's write our docs and reference these examples:
2024-07-10 17:46:18 +03:00
``` unison
2024-06-26 03:30:45 +03:00
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
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
@[source] List.take.ex2
🔽
@List .take.ex2 = @[evaluate] List.take.ex2
:]
2019-11-05 02:00:25 +03:00
```
2024-07-10 19:17:15 +03:00
``` ucm
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
Loading changes detected in scratch.u.
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
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
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
```
Let's add it to the codebase.
2019-11-05 02:00:25 +03:00
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-26 03:30:45 +03:00
scratch/main> add
2019-11-05 02:00:25 +03:00
2024-06-26 03:30:45 +03:00
⍟ I've added these definitions:
2019-12-15 18:25:29 +03:00
2024-06-26 03:30:45 +03:00
List.take.doc : Doc
2019-11-25 01:04:20 +03:00
2024-06-26 03:30:45 +03:00
```
We can view it with `docs` , which shows the `Doc` value that is associated with a definition.
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-26 03:30:45 +03:00
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.
2024-07-10 19:17:15 +03:00
``` ucm
2024-06-26 03:30:45 +03:00
scratch/main> view List.take
builtin lib.builtins.List.take :
lib.builtins.Nat -> [a] -> [a]
```