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.

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

standardise whether detailed descriptions & examples of types go on the type or the module #14967

Closed
huonw opened this issue Jun 17, 2014 · 7 comments · Fixed by #22549
Closed

Comments

@huonw
Copy link
Member

huonw commented Jun 17, 2014

E.g. Result is very brief, referring to the module std::result, which is very extensive, and even includes a redefinition of the Result type!

On the other hand std::collections::hashmap is short, while HashMap is more detailed (i'll note that these aren't precisely equivalent, since HashSet is in that module too). Similarly, Vec is longer than std::vec.

@huonw huonw added the A-docs label Jun 17, 2014
@huonw
Copy link
Member Author

huonw commented Jun 17, 2014

cc @steveklabnik

@huonw
Copy link
Member Author

huonw commented Jun 17, 2014

Other somewhat relevant modules:

@steveklabnik
Copy link
Member

My gut says "Full docs in the module, types should mention 'see module for full docs'

@aturon
Copy link
Member

aturon commented Jan 8, 2015

cc me

@Gankra
Copy link
Contributor

Gankra commented Jan 8, 2015

Steve's gut sounds right to me. Would especially work better if we had sane intra-links.

@Gankra
Copy link
Contributor

Gankra commented Jan 8, 2015

Although doc'ing the type can be more "portable" in the face of re-exports.

@aturon
Copy link
Member

aturon commented Feb 16, 2015

Hm, so I'm now starting to prefer the other direction.

Module-level docs are great for telling an overall narrative for people who are exploring, but they are not good when people are looking up a type/method etc. I guess the ideal option would be "both"? But I'm not really sure. As @gankro says links could help...

steveklabnik added a commit to steveklabnik/rust that referenced this issue Mar 4, 2015
This chapter covers writing documentation in depth.

Fixes rust-lang#4361
Fixes rust-lang#12862
Fixes rust-lang#14070
Fixes rust-lang#14967
bors added a commit that referenced this issue Mar 7, 2015
This chapter covers writing documentation in depth.

Fixes #4361
Fixes #12862
Fixes #14070
Fixes #14967
bors added a commit to rust-lang-ci/rust that referenced this issue Jun 5, 2023
…eykril

Revert "Add mandatory panic contexts to all threadpool tasks"

Reverts rust-lang/rust-analyzer#14965

This won't quite work actually given the use of `catch_unwind` in some of these
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants