-
Notifications
You must be signed in to change notification settings - Fork 72
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
Refactor docs to cover both names and identifiers #655
Conversation
Add more examples and document the additional shortening from names to identifiers that we've done in many cases.
While writing this I encountered a few issues:
Dear reviewers, please don't block this PR on figuring out the answers to all of these issues, but keep them in mind :) |
I think
Continuing from my previous point, perhaps we need a guideline for single interface method features. Those feel like "easy" cases where we might just use the method name and move on. In the case of
I think I'm responsible for these and I tried to rely phrases "known to be in widespread use by web developers." I tried to validate this by reading blog posts and Stack Overflow questions about their use. I don't think it'd be outrageous to use the unit names directly, but the description field fills that need too.
It wouldn't hurt to make that explicit for names, though I think the "lowercase alphanumeric" bit handles the identifiers already. (Also, I learned today that the values are case insensitive! I had long assumed that the sequence of bytes given by |
Over in #655 (comment), Philip makes a good case for preferring brevity over consistency across the whole set of features. (That said, we should prefer consistency when we add text to distinguish things for ambiguity, as in the case of arrays and typed arrays.) |
Add more examples and document the additional shortening from names to
identifiers that we've done in many cases.