KhronosGroup / KhronosGroup/OpenCL-Docs
Can we avoid duplicating the description and/or mention of (some) error codes?
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
See discussion on https://github.com/KhronosGroup/OpenCL-Docs/pull/118.
Many API functions can return generic error codes (e.g. CL_INVALID_). These error codes and their description are duplicated in the description of all API functions that use them. Is it possible to improve on this? A few ideas:
- Just mention the error code but link to the appendix for a description.
- Use macros to embed the description.
- Automatically generate these from the API description. Any function that takes a `cl_context`
for example will return `CL_INVALID_CONTEXT` if that context is invalid.
- Any other ideas?
Contributor guide
Research direction
Start with the discussion in pull request #118, then inspect the OpenCL-Docs API descriptions and appendix entries for duplicated error-code text. Compare the proposed linking, macro, and generation approaches with the current documentation structure. Done means an agreed approach is documented and the affected API references no longer duplicate descriptions.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100