-
Notifications
You must be signed in to change notification settings - Fork 22.5k
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
Remove CryptoKeyPair from MDN docs #8846
Conversation
Preview URLs
FlawsNone! 🎉 External URLsURL: No new external URLs URL: No new external URLs URL: No new external URLs URL: No new external URLs (this comment was updated 2021-09-13 00:51:25.176810) |
I worry a bit that this change makes the docs less useful. https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair seems like it tells us about a structure that's used a lot in public key crypto, and is referenced by quite a few other pages. It seems like a nice thing for, say, https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey to be able to say "returns a CryptoKeyPair" rather than "returns an object containing publicKey and privateKey properties". That just seems like a circumlocution. It seems like a nice thing for https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/decrypt to be able to say "If using RSA-OAEP, this is the privateKey property of the CryptoKeyPair object." rather than "If using RSA-OAEP, this is the privateKey property of an object containing a privateKey and publicKey." I guess I'm not sure what benefit is accruing to readers by making this change. I think there are cases where a dictionary is only used in one place, and it makes sense then to document it "inline" where it is used. But I'm not sure that in cases like this it is an improvement. |
I can understand that, I'll make sure to be more vigilant about dictionary removal from MDN web docs from now on! I'll back out these changes and only remove the BCD compat table. |
Ack, wait... The specifications' data now comes from BCD, if I remember correctly. How should we handle the spec section? |
Yes, there are a few (likely ≤ 5 ) dictionaries that are more interfaces without methods than just options. This is one of them.
No worry, we do review them :-)
We can hardcode the table in this case. |
So I'm closing this one. We will keep (at least for now) |
No worries. The sense I have is that we are still figuring out guidelines for when to remove dictionaries and when we should keep them. I'm not sure what the right answer is either, but we need to keep in mind what would be the most helpful thing for readers. About spec tables - I think it's a bit problematic that spec URLs are tied into BCD, for reasons like this. I think perhaps we should allow a |
This PR removes the documentation for the CryptoKeyPair dictionary from MDN. Correlates with its removal in BCD (see mdn/browser-compat-data#12346).