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

Docs: implementors list could be more readable #41879

Closed
ghost opened this issue May 10, 2017 · 5 comments
Closed

Docs: implementors list could be more readable #41879

ghost opened this issue May 10, 2017 · 5 comments
Labels
C-enhancement Category: An issue proposing an enhancement or a PR with one. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@ghost
Copy link

ghost commented May 10, 2017

Stable Rust: https://doc.rust-lang.org/std/ops/trait.Deref.html#tymethod.deref
Nightly Rust: https://doc.rust-lang.org/nightly/std/ops/trait.Deref.html#tymethod.deref

The docs on stable look better than on nightly.

The problem with nightly is that all these impls written one after another look rather messy.
A few ideas that might help:

  1. Add some spacing between consecutive impls.
  2. Place each impl entirely into a single line (don't place each where clause into a separate line).
  3. Place where and all following clauses into a dedicate line. This is what the stable docs do.

As a side node, the indentation of two spaces in the stable docs looks odd: 4 spaces would look better.

@frewsxcv
Copy link
Member

relevant to #41084

@steveklabnik steveklabnik added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label May 10, 2017
@steveklabnik steveklabnik added the T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. label May 18, 2017
@mulkieran
Copy link

See also #25061.

@Mark-Simulacrum Mark-Simulacrum added the C-enhancement Category: An issue proposing an enhancement or a PR with one. label Jul 27, 2017
@QuietMisdreavus
Copy link
Member

What's the current status of this? Where clauses have had a bit of a touch-up since this issue was posted, so i'd like to make sure what critiques still apply. (The main change that i think is new to this issue is that where clauses are now a bit smaller than the impl they apply to, and also associated types are printed for traits that have them.)

As to the suggestions in the OP:

  1. is simple enough, and would provide some visual clarity. Heck, this could probably be accomplished with just a CSS change.
  2. i would recommend against, simply for types that usually carry hefty where clauses around, like HashMap. Also because it goes against style guidelines, which is what the change that was around (and the one that currently stands) when this was posted was intended to move toward.
  3. See the "style guidelines" comment in (2). The stable that would have been around when this was posted was 1.17, so this is the page for Deref at that time.

@ghost
Copy link
Author

ghost commented Sep 29, 2017

FWIW, I'm quite happy with the current situation, except I'd still like to see some spacing between consecutive impls - they are squeezed a bit too closely together:

current nightly

And this is what it looks like if I change margin-bottom from 3px to 10px:

my suggestion

Might even go for 15px here... But this is just my personal preference in aesthetics. :)
Try playing with the impl list for IntoIterator - that one has a pretty hefty list.

Regarding the 2. and 3. point, yeah, let's stick to the style guidelines.

@QuietMisdreavus
Copy link
Member

QuietMisdreavus commented Sep 29, 2017

Here's what i get if i go for 1em instead:

image

This somewhat matches the spacing between paragraphs and headings farther up the page.

kennytm added a commit to kennytm/rust that referenced this issue Oct 13, 2017
…, r=QuietMisdreavus

Rustdoc: Increase padding between consecutive impls

Currently, [implementors](https://doc.rust-lang.org/nightly/std/iter/trait.IntoIterator.html#implementors) list is a bit too condensed. More spacing makes the list easier to read.
Check out [this comment](rust-lang#41879 (comment)) to see what's the effect of this change.

Closes rust-lang#41879.

cc @QuietMisdreavus
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-enhancement Category: An issue proposing an enhancement or a PR with one. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

5 participants