Enhance documentation for textOutput() and gridOutput() methods #8125
Conversation
…iling known limitations and alternatives for accessible canvas descriptions.
|
🎉 Thanks for opening this pull request! For guidance on contributing, check out our contributor guidelines and other resources for contributors! Thank You! |
There was a problem hiding this comment.
Pull Request Overview
This PR enhances the JSDoc documentation for the textOutput() and gridOutput() accessibility methods by adding comprehensive information about their known limitations and recommending alternative approaches.
- Added detailed documentation of limitations for both methods (English-only descriptions, WEBGL incompatibility, shape detection issues)
- Recommended
describe()anddescribeElement()as more accurate alternatives - Improved developer awareness of when these methods may not work as expected
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
src/accessibility/outputs.js
Outdated
| * `textOutput()` has several known limitations. Descriptions are only | ||
| * generated in English. Text drawn with <a href="#/p5/text">text()</a> is | ||
| * not described. `textOutput()` does not work with WEBGL mode or 3D shapes. | ||
| * 2D primitives rendered in WEBGL may be described incorrectly because the | ||
| * camera's perspective is not accounted for. Shapes with similar features may | ||
| * be combined in descriptions, resulting in inaccurate counts. Shapes | ||
| * positioned outside the canvas boundaries are described as though they're | ||
| * visible. Custom 2D shapes created with | ||
| * <a href="#/p5/beginShape">beginShape()</a> are not described. | ||
| * | ||
| * <a href="#/p5/describe">describe()</a> and | ||
| * <a href="#/p5/describeElement">describeElement()</a> provide more accurate | ||
| * and flexible alternatives for writing canvas descriptions. | ||
| * |
There was a problem hiding this comment.
Avoid absolute or negative phrasing like “does not work” and “inaccurate counts.” Prefer “not supported” and “may be imprecise.” Also, Keep a neutral, helpful tone. Also, the sketches in textOutputif you see 3rd and 4th are not working. https://p5js.org/reference/p5/textOutput/ Can this be fixed in your PR as well?
Resolves
Changes:
Updated JSDoc documentation for
textOutput()andgridOutput()insrc/accessibility/outputs.jsto clearly document known limitations.PR Checklist
npm run lintpasses