Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explain naming scheme for NodeBuilder, Action, DefaultActionVerb, etc, in documentation #402

Open
PoignardAzur opened this issue May 3, 2024 · 1 comment

Comments

@PoignardAzur
Copy link
Contributor

AccessKit includes a few types with undocumented methods, variants, etc:

It's clear enough that these method/variant names come from somewhere, but it's not clear what. My understanding from what you said is that the names come from the Chromium accessibility API? But I'm not sure what that API even is.

While in the long term it would be better to document every property, in the short term it would be nice if the four types listed above could include a link to respective page for the Chromium spec they draw from. This way people trying to understand AccessKit's semantics could at least use the Chromium spec as a starting point.

@PoignardAzur
Copy link
Contributor Author

I've had a chat with Matt on this subject. Some takeaways:

  • Accesskit's API is heavily inspired from Chromium's internal accessibility implementation. That implementation has no spec, no stability guarantees and doesn't match a specific API, which means we can't really link to it.
  • The overall question we need to solve it "What is the source of truth for the AccessKit API?" Right now, the ultimate source of truth is the platform bindings. In other words, the code is the spec. This isn't ideal for documentation either.

There are two long-term solutions we could pursue:

  • Align AccessKit to some existing standard like ARIA, documenting the correspondences and the divergences.
  • Make AccessKit its own standard, with a written spec, and make the spec the source of truth. Masonry would likely become the reference implementation.

Both solutions have trade-offs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant