KhronosGroup / KhronosGroup/OpenCL-Docs

[XML] Consistently group `<enum>`-s under their `<type>`

Open
#1,145 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
420
Forks
131
Avg merge
5d 13h
Merged PRs (30d)
11

Description

### The problem

High-level bindings benefit from grouping enum values under a common type name.
This allows verbose IntelliSense suggestions and avoids oversaturating the namespace with all the enum values in one place.

The `cl.xml` file in this repo already defined its own enum type for every enum group:
```
typedef cl_uint cl_device_local_mem_type;
...





...




```
However, there is currently no consistent way in which XML links the enum type (`cl_device_local_mem_type` above) and its valid values.

---

### Old solutions

The `` blocks seem to have been initially intended for this purpose.

However, this linkage was not maintained. At some point people just started adding all their new enums to:
```

```
#779 has tried to rectify this, but was abandoned.

Initially, I also tried to continue the work in #779, because I was already using (and un-messing in other ways) the `` tags.

But then realized that the moderate abuse of `comment` attributes on `` tags, of all things, was the most maintained form of such linkage between enums and their types.
I guess it's just a more natural form for it (in this repo at least).

---

### My solution

With that, I made #926, which currently replaces all the `comment` attributes referring to an enum type with a `group` attribute.

A few odd-balls of the `comment` attributes currently follow one of these 3 patterns:
```
# The "- bitfield" and the end (missing on some bitfields, I think I caught all of those)

...
# 2 enum types sharing tag

...
# Human-only text describing things like deprecation, also containing the actual enum type name

```
I've converted them into:
```
# Add etype (enum type/kind/usage), attribute

...
# Duplicate tag with all of its contents


...
# Leave the comment, because the deprecatedby attribute is not supported by inside

```
And a few remaining `` blocks with ``-s inside I've converted to either of these 2 `etype`-s:
```
# Mark non-grouped defines, denoting separate constants rather than enumerated values

...
# Mark enums, not used on the HOST side

```
My bindings' CI validates that no `` block with enums avoids this conversion.

---

### Future PRs

The `etype` attribute was made with an idea for another 2 kinds of enum-to-type linking metadata, which I wanted to transfer to this repo from my bindings because I think it would be useful for other XML consumers.

1. Object info enums:

- Enums in `cl_device_info` are each linked to a type of value the `clGetDeviceInfo` function returns;
- Enums in `cl_kernel_exec_info` are each linked to a type of value the `clSetKernelExecInfo` function accepts;
- Enums in `cl_kernel_sub_group_info` do both in the `clGetKernelSubGroupInfo` function.

2. Property list enums:
Enums in `cl_device_partition_property` are used to make lists, where values of other types are cast to `cl_device_partition_property` and then passed to the `clCreateSubDevices` function.

In particular:

- `CL_DEVICE_PARTITION_EQUALLY` is followed by a `cl_uint`;
- `CL_DEVICE_PARTITION_BY_COUNTS` is followed by a list of `cl_uint`-s;
- `CL_DEVICE_PARTITION_BY_COUNTS_LIST_END` terminates this list.

This metadata allows the creation of more strongly typed overloads in bindings.

I've already added and CI-validated (and then also maintained since the creation of #926) all this metadata to XML in the `custom` branch of my fork.
I'm not entirely happy with how I'm representing it in XML right now, and I'm ready to rewrite all of it.
But I think I'd rather make another issue after putting #926 to rest, on the off chance the extra questions about this metadata might stall the discussion about #926.
Well, I'll still answer here if anyone wants to talk about this metadata in this thread.

---

Any suggestions on how this could be done better?
Seriously, I'd take any scrutiny over having #926 just sit for even longer...

Contributor guide

Open the contributing guide

Research direction

Start with cl.xml and review the enum groups, require blocks, and the proposed changes in #926. Determine whether the group and etype metadata scheme should be adopted consistently, including the listed bitfield, shared-type, constants, and OpenCL-C-only cases; done means the project has an agreed, consistently applied linkage.

Written by the indexing model from the issue text.

Assessment

Tech stack
xml
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.