KhronosGroup / KhronosGroup/OpenCL-Docs
[XML] Consistently group `<enum>`-s under their `<type>`
- 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
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