Verified Commit 6b4a07c7 authored by Camil Staps's avatar Camil Staps 🙂

Update readme

parent c46bd4bc
......@@ -10,124 +10,33 @@ using generic JSON encode and decode functions. The functions in `Cloogle.DB`
provide low-level access to modify the database and search in it.
The `Cloogle.DB.Factory` module hooks into the Clean compiler to provide
functions to populate a type database by parsing Clean source code. For
indexing documentation it was needed to patch the Clean compiler. To this end,
some modules from the frontend of the compiler have been replicated in
`/compiler-patch`. This directory should be added to the `clm` include paths
before the paths of the compiler.
functions to populate a type database by parsing Clean source code.
The functions in `Cloogle.Search` provide a higher level API to the type
database, using the common Cloogle types defined by
[libcloogle](https://gitlab.science.ru.nl/cloogle/libcloogle).
## Dependencies
The Clean compiler is needed to build the database (not to use it).
Unfortunately, it is [developed on subversion][cocl] which means we can't add
it as a git submodule. The compiler patches are compatible with revision 2838
(2017-10-26). The compiler can be fetched and patched by running `make
clean-compiler`.
## 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,
documentation fields can be added with `@`. Currently, documentation fields
should have only one line.
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]
```
it as a git submodule. To get the latest version of the compiler that this
project is compatible with, run `make clean-compiler`. This rule should always
be run, because it checks itself whether an update is needed. If you depend on
Cloogle in your project, a good rule to add to your Makefile is:
`@result` can be given multiple times for tuples.
```make
Cloogle/clean-compiler: .FORCE
$(MAKE) -C Cloogle clean-compiler
For short documentation items, doclines, starting with `//*` can be used. When
documenting a constructor, or record field, they should be placed *after* the
item they document. Doclines are only supported for constructors and record
fields. For example:
.FORCE:
```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
}
.PHONY: .FORCE
```
### Markup 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.
### 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.
| | 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] | | |
| Instance | | | | | | | |
| 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 CleanTypeUnifier's `pdType` can
do), `CloogleDBFactory` can derive the type.</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][].
## Copyright &amp; License
Copyright &copy; 2016-present Mart Lubbers and Camil Staps.
Copyright &copy; 2016&ndash;present Mart Lubbers and Camil Staps.
Licensed under MIT; See the [LICENSE](/LICENSE) file.
[Clean]: http://clean.cs.ru.nl
[Cloogle]: https://cloogle.org
[cocl]: https://svn.cs.ru.nl/repos/clean-compiler
[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
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