RustCrypto / RustCrypto/hashes

docs for hasher states could use a reference to the `Digest` trait

Open
#441 5 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
2.3k
Forks
340
Avg merge
12h 31m
Merged PRs (30d)
2

Description

For someone new to the ecosystem it might be hard to tell how to use a... For example, sha3::Keccak256 (https://docs.rs/sha3/latest/sha3/type.Keccak256.html), it's just a type alias with no real info about what it is (other than some nebulous "hasher state") or how to use it. I'd recommend linking to the Digest trait in the docs as a way of explaining "how to use it"

Additionally (if I should move this to a separate issue, let me know and I will do so) I would recommend an example specifically showing how to sha3::Keccak256::digest(b"a message") in one go. Finally, the example(s) that use update should add more than one message. This would be so that show new user why you would use new and then update rather than digest ("because you can add more than one thing").

I would be willing to create the examples / documentation if this would be agreeable

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the documentation for hasher state types such as sha3::Keccak256 and the existing examples using Digest::update. Add a reference to the Digest trait, show a one-shot Keccak256::digest example, and use multiple messages in incremental examples so the distinction is clear. The documentation is done when newcomers can understand both usage patterns.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cryptography, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.