mirror of
https://github.com/unisonweb/unison.git
synced 2024-09-11 02:25:39 +03:00
2.1 KiB
2.1 KiB
Documenting Unison code
scratch/main> builtins.merge lib.builtins
Unison documentation is written in Unison. Documentation is a value of the following type:
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:
doc1 = [: This is some documentation.
It can span multiple lines.
Can link to definitions like @List.drop or @List
:]
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 ofList.take
@[source] List.map
expands to the full source ofList.map
@[include] someOtherDoc
, inserts a valuesomeOtherDoc : Doc
here.@[evaluate] someDefinition
expands to the result of evaluatingsomeDefinition
, 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:
List.take.ex1 = take 0 [1,2,3,4,5]
List.take.ex2 = take 2 [1,2,3,4,5]
scratch/main> add
And now let's write our docs and reference these examples:
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
:]
Let's add it to the codebase.
scratch/main> add
We can view it with docs
, which shows the Doc
value that is associated with a definition.
scratch/main> docs List.take
Note that if we view the source of the documentation, the various references are not expanded.
scratch/main> view List.take