DOCUMENTATION.md 5.32 KB
Newer Older
1 2 3 4 5
# Clean documentation
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,
6 7
documentation fields can be added with `@`. Currently, documentation fields
should have only one line.
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

An example is below:

```clean
/**
 * Apply a function to every element in a list.
 *
 * @param The function
 * @param The list
 * @result The new list
 */
map :: (a -> b) [a] -> [b]
```

`@result` can be given multiple times for tuples.

For short documentation items, doclines, starting with `//*` can be used. When
documenting a constructor, or record field, they should be placed *after* the
26
item they document. For example:
27 28 29 30 31 32 33 34 35 36 37 38

```clean
/**
 * A date in the Gregorian calendar
 */
:: Date =
	{ day   :: Int  //* The day of the month, starting with 1
	, month :: Int  //* The month (January is 1)
	, year  :: Int  //* The year
	}
```

39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
To add several lines of documentation to a constructor or record field, several
doclines can be used:

```clean
:: MyType
	= MyConstructor args // ...
		//* This constructor may require some more explanation,
		//* which is added on several lines.
```

Doclines can also be added *above* a function, type, or class definition:

```clean
//* The identity function.
id :: .a -> .a
```

56 57
## Markup in documentation

58
Some simple Markdown-inspired markup is allowed in documentation:
59 60

- `` `foo` `` renders `foo` in monospaced font.
61 62 63
- 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 ``.
64 65 66 67 68 69 70 71 72 73
- `{{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.

## Documentation fields

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.

74 75 76 77 78
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.

79 80 81 82 83 84 85
|              | Description | `@param` | `@result` | `@type` | `@var` | `@representation` | `@throws` | `@complexity`
|--------------|-------------|----------|-----------|---------|--------|-------------------|-----------|--------------
| Class        | ![][y]      | ![][y]<sup>1</sup> | ![][y]<sup>1</sup> | | ![][y]          |           |
| Class member | ![][y]      | ![][y]   | ![][y]    |         |        |                   | ![][y]    | ![][y]
| Constructor  | ![][y]      |          |           |         |        |                   |           |
| Function     | ![][y]      | ![][y]   | ![][y]    |         |        |                   | ![][y]    | ![][y]
| Generic      | ![][y]      | ![][y]   | ![][y]    |         | ![][y] |                   |           |
86
| Instance     | ![][y]      |          |           |         |        |                   |           |
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
| Macro        | ![][y]      | ![][y]   | ![][y]    | ![][y]<sup>2</sup> | |               |           |
| Module       | ![][y]      |          |           |         |        |                   |           |
| Record field | ![][y]      |          |           |         |        |                   |           |
| Type         | ![][y]      |          |           |         | ![][y] | ![][y], for type synonyms |   |

<sup>1: only for shorthand classes like `class zero a :: a`, where there is no
other place for the documentation of the class member.</sup>  
<sup>2: for simple macros (depending on what the type deriver in
`Clean.Types.CoclTransform` can do), Cloogle will derive the type if it is not
given.</sup>

| Field             | Description
|-------------------|-------------
| `@complexity`     | E.g. "O(n log n)".
| `@param`          | Parameters of a function(-like). Name a parameter using `@param name: description`.
| `@representation` | The representation of a synonym type.
| `@result`         | The result of a function.
| `@return`         | A deprecated synonym of `@result`.
| `@throws`         | iTasks exceptions that can be thrown.
| `@type`           | The type of a macro (without name and `::`).
| `@var`            | Type variables of types, classes and generics.

### Property documentation

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][].

115 116 117 118 119 120 121 122 123 124 125 126
Our [standards](STANDARDS.md) require the use of tabs for indentation and spaces
for outlining. Because with properties code is included in documentation blocks,
using tabs for indentation would lead to tabs after spaces. To avoid this, we
use four spaces in this context instead. For example:

```clean
/**
 * @property correctness: A.xs :: Set a:
 *     minList (toList xs) == findMin xs
 */
```

127 128 129 130
[clean-test-properties]: https://gitlab.science.ru.nl/clean-and-itasks/clean-test-properties
[Gast]: https://gitlab.science.ru.nl/clean-and-itasks/gast

[y]: http://i.stack.imgur.com/iro5J.png