mirror of
https://github.com/unisonweb/unison.git
synced 2024-09-11 02:25:39 +03:00
Port doc1 transcript to projects
This commit is contained in:
parent
3666e04257
commit
2fd585e1d3
@ -1,13 +1,13 @@
|
|||||||
# Documenting Unison code
|
# Documenting Unison code
|
||||||
|
|
||||||
```ucm:hide
|
```ucm:hide
|
||||||
scratch/main> builtins.merge
|
scratch/main> builtins.merge lib.builtins
|
||||||
```
|
```
|
||||||
|
|
||||||
Unison documentation is written in Unison. Documentation is a value of the following type:
|
Unison documentation is written in Unison. Documentation is a value of the following type:
|
||||||
|
|
||||||
```ucm
|
```ucm
|
||||||
scratch/main builtin> view Doc
|
scratch/main> view 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:
|
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:
|
||||||
@ -42,7 +42,7 @@ List.take.ex2 = take 2 [1,2,3,4,5]
|
|||||||
```
|
```
|
||||||
|
|
||||||
```ucm
|
```ucm
|
||||||
scratch/main builtin> add
|
scratch/main> add
|
||||||
```
|
```
|
||||||
|
|
||||||
And now let's write our docs and reference these examples:
|
And now let's write our docs and reference these examples:
|
||||||
@ -67,17 +67,17 @@ List.take.doc = [:
|
|||||||
Let's add it to the codebase.
|
Let's add it to the codebase.
|
||||||
|
|
||||||
```ucm
|
```ucm
|
||||||
scratch/main builtin> add
|
scratch/main> add
|
||||||
```
|
```
|
||||||
|
|
||||||
We can view it with `docs`, which shows the `Doc` value that is associated with a definition.
|
We can view it with `docs`, which shows the `Doc` value that is associated with a definition.
|
||||||
|
|
||||||
```ucm
|
```ucm
|
||||||
scratch/main builtin> docs List.take
|
scratch/main> docs List.take
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that if we view the source of the documentation, the various references are *not* expanded.
|
Note that if we view the source of the documentation, the various references are *not* expanded.
|
||||||
|
|
||||||
```ucm
|
```ucm
|
||||||
scratch/main builtin> view List.take
|
scratch/main> view List.take
|
||||||
```
|
```
|
||||||
|
@ -3,26 +3,157 @@
|
|||||||
Unison documentation is written in Unison. Documentation is a value of the following type:
|
Unison documentation is written in Unison. Documentation is a value of the following type:
|
||||||
|
|
||||||
```ucm
|
```ucm
|
||||||
☝️ The namespace .builtin is empty.
|
scratch/main> view lib.builtins.Doc
|
||||||
|
|
||||||
.builtin> view Doc
|
type lib.builtins.Doc
|
||||||
|
= Blob Text
|
||||||
⚠️
|
| Link Link
|
||||||
|
| Source Link
|
||||||
The following names were not found in the codebase. Check your spelling.
|
| Signature Term
|
||||||
Doc
|
| 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
|
||||||
|
|
||||||
The transcript failed due to an error in the stanza above. The error is:
|
:]
|
||||||
|
```
|
||||||
|
|
||||||
|
```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:
|
||||||
|
|
||||||
The following names were not found in the codebase. Check your spelling.
|
⍟ These new definitions are ok to `add`:
|
||||||
Doc
|
|
||||||
|
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]
|
||||||
|
|
||||||
|
```
|
||||||
|
Loading…
Reference in New Issue
Block a user