KhronosGroup / KhronosGroup/SYCL-Docs
Comments in class synopses are inconsistent
- Dominant language
- JavaScript
- Stars
- 158
- Forks
- 80
- Avg merge
- 7d 6h
- Merged PRs (30d)
- 5
Description
### Specification Version
SYCL 2020 (Revision 9)
### Section Number(s)
This applies throughout the specification.
### Issue Description
Throughout the specification, class synopses include comments like this:
```c++
/* -- common interface members -- */
backend get_backend() const noexcept;
```
The first time that I read the specification, I thought this was a section header (i.e., that `get_backend()` in this example _is_ a "common interface member"). I do not think it is obvious at all that this comment is actually intended to represent a list of functions that aren't shown.
This is made worse by the fact that there are many instances of block comments _are_ used to describe the next line:
```c++
/* Available only when: T != float */
T fetch_add(T operand, memory_order memoryOrder = memory_order::relaxed);
```
I think the correct fix is to list out the common interface members explicitly for each of these classes.
### Code Example (Optional)
_No response_
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the SYCL 2020 specification's class synopses and compare comments that label omitted common interface members with comments describing the following declaration. Identify each affected synopsis, then make the common interface members explicit throughout; the work is done when those comments no longer appear to be section headers or are clearly distinguished from declaration-specific comments.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100