KhronosGroup / KhronosGroup/OpenCL-Docs

Can we avoid duplicating the description and/or mention of (some) error codes?

Open
#120 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

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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.