google/webcrypto.dart

Consider using [!NOTE] blockquote for browser/platform compatibility notes

Closed this issue · 10 comments

jonasfj commented

In: https://pub.dev/documentation/webcrypto/latest/webcrypto/AesCtrSecretKey/encryptBytes.html

And a few other places we write: **Remark** ... to indicate that a particular browser or platform doesn't support a particular feature.

Instead of using this form, it'd be cool to use the [!NOTE] format.

Example

Note

Remark Firefox does not implement counter rollover for AES-CTR correctly. Picking a sufficiently large length and using a counter that isn't filled with 0xff will likely avoid counter rollovers. See bug 1803105 for details.

Markdown

> [!NOTE]
> Remark Firefox does not implement counter rollover for AES-CTR correctly. Picking a sufficiently large `length` and using a `counter` that isn't filled with 0xff will likely avoid counter rollovers. See [bug 1803105](https://bugzilla.mozilla.org/show_bug.cgi?id=1803105) for details.

I think this should work with recent versions of dartdoc too! 🚀

We should test it out locally first, and we should make sure to migrate all such remarks in one PR.

TropicolX commented

Hi @jonasfj. Can I be assigned to this?

jonasfj commented

Done,

jonasfj commented

There is a thread about this package in the #packages channel on dart_community

https://dart.dev/community

Feel free to join and say hi.

TropicolX commented

Alright, thanks!
Will do

TropicolX commented

Hi @jonasfj,
How do I test out the changes locally? Can I get a preview UI similar to this: https://pub.dev/documentation/webcrypto/latest/webcrypto/AesCtrSecretKey/encryptBytes.html

jonasfj commented

(1) is perfect, that's what I imagined this bug would address.

But (2) and (3) also seem appropriate.

Unrelated, but in the case of (2), I asked around and it was suggested that if we gave the enum a private member. Then people wouldn't be able to switch over it without having a default case.

This is unrelated, but we should consider adding a private member to discourage people from making the assumption that new values won't be added in the future.

TropicolX commented

Hi @jonasfj, thanks for the review.
I've created a PR for the issue here #126

Regarding the enum, I have no idea how to add a private member to an enum in dart 😅 but I'd love to look into it. Any pointers on how to do this would also be appreciated.

jonasfj commented

Fixed in #126

@TropicolX pro tip: If you write Fixed #115 in the description of a PR, then it'll close the associated issue when the PR is landed.

  • 👍1