KhronosGroup / KhronosGroup/SYCL-Docs

Comments in class synopses are inconsistent

Open
#878 1 comment 0 reactions 0 assignees View on GitHub
clarification
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.