rust-lang / rust-lang/hashbrown

Properly document algorithm

Open
#454 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
3k
Forks
358
Avg merge
11h 57m
Merged PRs (30d)
2

Description

Note: this also applies to the libstd documentation, since it just reuses the same documentation exported in this crate.

Right now, the only documentation available for the hashbrown implementation, excluding the code itself (which is not documentation), is these this:

The hash table implementation is a Rust port of Google’s SwissTable. The original C++ version of SwissTable can be found here, and this CppCon talk gives an overview of how the algorithm works.

As far as I'm aware, the algorithm is not a clear-cut port of the C++ version, and there are definitely changes to how the internals work. Additionally, I don't consider the talk documentation, since while it may be an excellent introduction and provides motivation to the concept, it is in no way documenting how the table actually works.

While I understand that the purpose of a general hash map is to avoid concerning users with the details, I think that documenting how exactly this implementation works is useful to both those trying to implement their own variations, or those who wish to work with the source code and modify it in some way.

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 reading the existing documentation exported by the hashbrown implementation and reused in the libstd documentation, then compare it with the linked SwissTable references and the implementation source. Done means documenting how this implementation works, including its differences from the original C++ version, for both users studying the algorithm and contributors modifying the source.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.