Documentation of usage. #36
Conversation
README.md
Outdated
| @@ -1,14 +1,110 @@ | |||
| # Library of cryptographic functions for Dart | |||
| # Cryptographic digest functions for Dart | |||
There was a problem hiding this comment.
"Digest" is kind of confusing term here—in my experience, "hash" is used much more widely in practice. Can you consistently refer to them as "hashes" unless you're specifically talking about the Digest class?
README.md
Outdated
| * Converting a Base 64 encoded String into list of bytes. | ||
| * SHA-1 | ||
| * SHA-256 | ||
| * HMAC (i.e. HMAC-MD5, HMAC-SHA1, HMAC-SHA256) |
There was a problem hiding this comment.
It would be nice to link these to the relevant API documentation.
README.md
Outdated
| Invoke the `convert` method, passing the input data as a sequence of | ||
| bytes (i.e. `List<int>`). It returns a `Digest` object, where the | ||
| digest value can be obtained as bytes in a `List<int>` or encoded in | ||
| hexadecimal as a `String`. |
There was a problem hiding this comment.
These paragraphs are pretty verbose. Maybe "Use sha256.convert(), sha1.convert(), or md5.convert() to hash a list of bytes." (with links to the API docs). Generally, I prefer including the more detailed usage information in the code snippet, since it's easy for users to see how it's invoked there.
README.md
Outdated
| import 'package:crypto/crypto.dart'; | ||
| import 'dart:convert'; // for the UTF8.encode method | ||
|
|
||
| ... |
There was a problem hiding this comment.
I try to make my example code snippets valid stand-alone Dart programs if possible, which means writing out a main() method.
README.md
Outdated
| Do not use the `codeUnits` property of a `String`, unless it is | ||
| _guaranteed_ the string will never contain characters outside the | ||
| range of 0-255. Even then, characters in the range of 128-255 might | ||
| produce the wrong result. |
There was a problem hiding this comment.
I don't think this is necessary here—it's not really a property of this library, but of the general way Dart handles binary data and strings.
README.md
Outdated
| range of 0-255. Even then, characters in the range of 128-255 might | ||
| produce the wrong result. | ||
|
|
||
| ### Digest on chunked input |
There was a problem hiding this comment.
All of this stuff comes from the core library's Converter API. I'm not sure it's worth giving a full tutorial for it here, as opposed to just linking to that documentation (and improving it if necessary).
There was a problem hiding this comment.
Looks like you missed this comment.
There was a problem hiding this comment.
The "tutorial" was all deleted.
|
All requested changes have been performed. Links to the relevant API documentation have been added for the variables/classes in a new paragraph just before the first example. This is better because the algorithms are not the same as a particular implementation of the algorithms. And the list is cleaner too. |
README.md
Outdated
|
|
||
| The variables [`sha256`][sha256], [`sha1`][sha1], and [`md5`][md5] are | ||
| instances of the [`Sha256`][Sha256], [`Sha1`][Sha1], and [`MD5`][MD5] | ||
| classes, respectively. |
There was a problem hiding this comment.
I don't think this sentence is particularly useful. It's easy for users to look at the documentation and see the class structure, but in terms of real-world usage they're going to be dealing exclusively with the constants themselves.
README.md
Outdated
| Or use the `sha1` or `md5` properties to use those other digest | ||
| algorithms. | ||
| Use `sha256.convert()`, `sha1.convert()`, or `md5.convert()` to hash a | ||
| list of bytes. |
README.md
Outdated
|
|
||
| print("HMAC digest as bytes: ${digest.bytes}"); | ||
| print("HMAC digest as hex string: $digest"); | ||
| } | ||
| ``` | ||
|
|
||
| ## Test status |
There was a problem hiding this comment.
Can you remove this and everything below it? It's inaccurate and redundant at this point.
README.md
Outdated
| range of 0-255. Even then, characters in the range of 128-255 might | ||
| produce the wrong result. | ||
|
|
||
| ### Digest on chunked input |
There was a problem hiding this comment.
Looks like you missed this comment.
|
Done. |
|
/ping I think this PR will be very useful. E.g. I was searching for 'sha256' on pub, and the |
|
This is great progress. If there's any cleanup, we can do it in a follow-up, PR. |
Added documentation in the README file on how to use this package.
This should make it easier for people to use it.