KhronosGroup / KhronosGroup/SYCL-Docs
Canonical ordering for new format API definition paragraph headings
- Dominant language
- JavaScript
- Stars
- 158
- Forks
- 80
- Avg merge
- 7d 6h
- Merged PRs (30d)
- 5
Description
The new spec format has the following structure for API definitions:
```asciidoc
// (Asciidoc gobbledygook)
---
void foo()
---
Statement1
_Heading:_
* Bullet
_Heading:_
* Bullet
...
Statement2
```
Possible values for `Heading` that currently appear in the spec are:
* `Constraints`
* `Preconditions`
* `Throws`
* `Effects`
* `Returns`
* `Remarks`
* `Availability`
`Statement1` and `Statement2` include things like deprecation notes, non-normative notes, and free-form statements similar to remarks. The ordering of the various fields is currently inconsistent.
It would be great if we could agree on what the canonical API definition should look like, and specifically what order the various fields should come in. (Obviously, most real definitions won't have all fields present.) It's currently also not clear to me how function parameters should be documented.
Contributor guide
No contributing guide indexed for this repository
Research direction
Review existing API definitions in the SYCL specification and compare the current ordering of Constraints, Preconditions, Throws, Effects, Returns, Remarks, and Availability. Also examine how function parameters and free-form statements are currently documented. Done means an agreed canonical structure and clear guidance for optional fields and parameters.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100