Verified Commit 88d48520 authored by Camil Staps's avatar Camil Staps 🚀

Update Clean.Doc documentation and link from STANDARDS.md

parent b4f18f1e
Pipeline #15350 passed with stage
in 1 minute and 15 seconds
......@@ -3,7 +3,8 @@ Cloogle indexes documentation of the syntax elements it stores, through
functions in `Clean.Doc`. Docblocks are comments that start with `/**` and have
a leading asterisk on every line (leading whitespace is ignored). The first
part of the docblock is taken as a general description. Below the description,
documentation fields can be added with `@`.
documentation fields can be added with `@`. Currently, documentation fields
should have only one line.
An example is below:
......@@ -38,9 +39,12 @@ fields. For example:
## Markup in documentation
Some simple markup is allowed in documentation:
Some simple Markdown-inspired markup is allowed in documentation:
- `` `foo` `` renders `foo` in monospaced font.
- Code blocks can be surrounded by `` ``` `` on separate lines. The start of a
code block can indicate the language (for highlighting purposes), as in
`` ```clean ``.
- `{{bar}}` marks `bar` as a defined entity (that can be searched for).
- Double newlines distinguish paragraphs; single newlines are ignored unless
followed by a hyphen.
......@@ -51,6 +55,11 @@ The tables below describe which fields and documentation types can be used for
different syntax elements, and what they should document. An extension, to
document test properties, is discussed below.
What fields are accepted for what syntax elements is defined by the records in
`Clean.Doc`; how they are parsed in the instances of the generic function
`docBlockToDoc`. The below is merely a convenient representation of the same
information.
| | Description | `@param` | `@result` | `@type` | `@var` | `@representation` | `@throws` | `@complexity`
|--------------|-------------|----------|-----------|---------|--------|-------------------|-----------|--------------
| Class | ![][y] | ![][y]<sup>1</sup> | ![][y]<sup>1</sup> | | ![][y] | |
......@@ -87,23 +96,6 @@ With [clean-test-properties][]' `testproperties` tool, [Gast][] test programs
can be generated with properties from docblocks. For this, several additional
fields can be used, which are further documented by [clean-test-properties][].
Briefly, `@property` on functions describes the actual property. When this uses
type variables, `@property-test-with` can be used to show how to instantiate
them. On the module, `@property-bootstrap` can be used to add bootstrap code,
like imports, to the top of the program. For example:
```clean
/**
* @property plus_commutative: A. x :: a; y :: a:
* x + y == y + x
* @property-test-with a = Int
* @property-test-with a = Real
*/
```
This will test the property `\x y -> x + y == y + x` where `x` and `y` are of
type `Int` or `Real`.
[clean-test-properties]: https://gitlab.science.ru.nl/clean-and-itasks/clean-test-properties
[Gast]: https://gitlab.science.ru.nl/clean-and-itasks/gast
......
......@@ -70,11 +70,11 @@ id x = x
```
Several JavaDoc like parameters are supported such as `@param`, `@result`,
`@type`, `@var` and `@representation`. More info about this can be found
[here](https://gitlab.science.ru.nl/cloogle/Cloogle#clean-documentation).
We use `@complexity` for the complexity order. Some other special fields are
used, like `@gin-icon`, but one should be reluctant with inventing new field
names. If there is a general use case, adding it can be discussed.
`@type`, `@var` and `@representation`. More info about this can be found in
[DOCUMENTATION.md](DOCUMENTATION.md). We use `@complexity` for the complexity
order. Some other special fields are used, like `@gin-icon`, but one should be
reluctant with inventing new field names. If there is a general use case,
adding it can be discussed.
## Layout
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment