Skip to content
GitLab
Projects
Groups
Snippets
Help
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
C
clean-platform
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
16
Issues
16
List
Boards
Labels
Service Desk
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Operations
Operations
Incidents
Environments
Analytics
Analytics
CI / CD
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
clean-and-itasks
clean-platform
Commits
88d48520
Verified
Commit
88d48520
authored
Oct 21, 2018
by
Camil Staps
🚀
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Update Clean.Doc documentation and link from STANDARDS.md
parent
b4f18f1e
Pipeline
#15350
passed with stage
in 1 minute and 15 seconds
Changes
2
Pipelines
1
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
16 additions
and
24 deletions
+16
-24
doc/DOCUMENTATION.md
doc/DOCUMENTATION.md
+11
-19
doc/STANDARDS.md
doc/STANDARDS.md
+5
-5
No files found.
doc/DOCUMENTATION.md
View file @
88d48520
...
...
@@ -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
...
...
doc/STANDARDS.md
View file @
88d48520
...
...
@@ -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 ar
e
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 b
e
reluctant with inventing new field names. If there is a general use case,
adding it can be discussed.
## Layout
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment