Skip to content
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.

Sign up for GitHub

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

Jump to bottom

API Docs: hash #29357

Closed
4 tasks
steveklabnik opened this issue Oct 26, 2015 · 9 comments · Fixed by #41125
Closed
4 tasks

API Docs: hash #29357

steveklabnik opened this issue Oct 26, 2015 · 9 comments · Fixed by #41125
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. E-mentor Call for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion. P-medium Medium priority

Comments

@steveklabnik
Copy link
Member

steveklabnik commented Oct 26, 2015 •
edited
Loading

Part of #29329

http://doc.rust-lang.org/std/hash/

Here's what needs to be done to close out this issue:

  • BuildHasherDefault needs a stronger summary/explanation distinction. "This structure is zero-sized and does not need construction." is weird.
  • BuildHasher also needs a stronger summary/explanation distinction. It also needs a better explanation of why it exists with an example.
  • Hash needs general improvement, it is the main bit of this module, but its docs feel tossed together and have few examples or coherence.
  • Hasher needs more than just a summary line; it needs explanation and examples.
@steveklabnik steveklabnik mentioned this issue Oct 26, 2015
Closed
51 tasks
@adrianbrink
Copy link

What kind of further documentation are you looking for here? @steveklabnik

@steveklabnik
Copy link
Member Author

Better explanations for https://doc.rust-lang.org/std/hash/struct.BuildHasherDefault.html

examples of implementing https://doc.rust-lang.org/std/hash/trait.BuildHasher.html and https://doc.rust-lang.org/std/hash/trait.Hash.html and https://doc.rust-lang.org/std/hash/trait.Hasher.html and more docs generally for all three.

@piordanov
Copy link

There seem to be a lengthy example of BuildHasherDefault added in this commit (d409fc3)

Also for BuildHasher and Hash.html there is a healthy amount of documentation as of now. Hasher seems to be really outdated (still lists several Implementors without mentioning they have been deprecated), which I'm looking into right now.

@brson
Copy link
Contributor

brson commented Feb 26, 2017

Thanks @piordanov ! Looks like all that's left is documenting Hasher.

@steveklabnik steveklabnik added the E-mentor Call for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion. label Mar 8, 2017
@steveklabnik
Copy link
Member Author

I am happy to mentor anyone who wants to tackle this issue.

@adrianbrink
Copy link

@steveklabnik I volunteer as a tribute :-)

@steveklabnik
Copy link
Member Author

@adrianbrink wonderful! If you need any help, please just let me know, as I said above, happy to help you help me 😄 (We can do it here or ping me on IRC)

@steveklabnik steveklabnik added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Mar 10, 2017
@projektir projektir mentioned this issue Mar 14, 2017
Closed
@steveklabnik
Copy link
Member Author

@adrianbrink I have added more specifics in the main issue above

@steveklabnik steveklabnik added P-medium Medium priority E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. and removed A-docs labels Mar 24, 2017
@chordowl
Copy link
Contributor

chordowl commented Apr 5, 2017 •
edited
Loading

I'm gonna tackle this one this weekend! (if that's okay with you, @adrianbrink)

@chordowl chordowl mentioned this issue Apr 6, 2017
Merged
4 tasks
frewsxcv added a commit to frewsxcv/rust that referenced this issue Apr 15, 2017
@frewsxcv
Rollup merge of rust-lang#41125 - lukaramu:std-hash-docs, r=frewsxcv
3f79bdc 
Improve std::hash docs

Fixes rust-lang#29357.

For details on what exactly I've done, see the commit descriptions.

There are some things I'm not sure about, but would like to address before merging this so the issue can be closed; any feedback on these points would really be appriciated:
* [x] ~I didn't touch the module level docs at all. On the one hand, I think they could use a short overview over the module; on the other hand, the module really isn't that big and I don't know if I could really do anything beyond just duplicating the type's summaries...~
* [x] ~I feel like the module-level examples are quite long-winded and not to the point, but I couldn't really think of anything better. Any ideas?~
* [x] ~Should `Hasher` get an example for implementing it? There is one in the module documentation, but it only "implements" it via `unimplemented!` and I'm not sure what the value of that is.~
* [x] ~Should `Hasher`'s `write_{int}` methods get examples?~

If there's anything else you'd like to see in std::hash's docs, please let me know!

r? @rust-lang/docs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools E-help-wanted Call for participation: Help is requested to fix this issue. E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. E-mentor Call for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion. P-medium Medium priority
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Improve std::hash docs
5 participants
@steveklabnik @brson @chordowl @piordanov @adrianbrink