KhronosGroup / KhronosGroup/SYCL-Docs

Canonical ordering for new format API definition paragraph headings

Open
#734 2 comments 0 reactions 0 assignees View on GitHub
editorial
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.