Document ARIA mappings for string properties#753
Conversation
DataTriny
left a comment
DataTriny
left a comment
There was a problem hiding this comment.
Thank you for starting this.
Overall I think the format is good, except mentionning when there is no equivalent.
| /// An [IETF language tag](https://www.rfc-editor.org/info/bcp47). | ||
| /// Only present when different from parent. | ||
| /// Only set this when it differs from the parent. There is no ARIA equivalent; | ||
| /// web content supplies this information through the host language. |
There was a problem hiding this comment.
I don't think we want to talk about web content specifically. Saying that the default value is dictated by the host platform is obvious but maybe needs to be documented? @PoignardAzur
DataTriny
left a comment
DataTriny
left a comment
There was a problem hiding this comment.
It's looking good. Just two more improvements from me.
I'd value @PoignardAzur's opinion on this before merging.
| /// web content supplies this information through the host language. | ||
| /// Only set this when it differs from the parent. | ||
| (Language, language, set_language, clear_language), | ||
| /// If a text input has placeholder text, it should be exposed |
There was a problem hiding this comment.
I think we're missing an introductory sentence to explain the purpose.
From ARIA: "A short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format."
Then reword the mention of Node::label as ARIA does too.
There was a problem hiding this comment.
Not sure if we clearly communicate the fact that placeholder and label can be used in conjunction, they serve different purposes. ARIA does it well, at least people can click on the link.
DataTriny
left a comment
DataTriny
left a comment
There was a problem hiding this comment.
Looks good to me.
Let's give Olivier a chance to go through this.
PoignardAzur
left a comment
PoignardAzur
left a comment
There was a problem hiding this comment.
I tried running cargo doc and the generated docs seem fine. I think the format is good as-is.
Some of the descriptions seem a little vague about how this data will be interpreted, but that's par for the course with accessibility standards, and this will do for now.
Thanks for the PR!
3 participants
This is a first pass at #749, starting with the string properties as discussed.
The inline documentation covers the following -:
ValueandKeyboardShortcut.The newer row and column index text and Braille properties link to the WAI-ARIA 1.3 draft and are identified as draft equivalents.
This is intentionally limited to one property type so we can agree on the format and wording before expanding the documentation further.
I ran the following checks,-
cargo fmt --all -- --checkRUSTDOCFLAGS="-D warnings" cargo doc -p accesskit --no-depscargo test -p accesskitHappy to revise anything if required.