Rust: Docs: implementors list could be more readable

Created on 10 May 2017  路  5Comments  路  Source: rust-lang/rust

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.

C-enhancement T-dev-tools T-rustdoc

Most helpful comment

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.

All 5 comments

See also #25061.

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.

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.

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.

Was this page helpful?
0 / 5 - 0 ratings

Related issues

nikomatsakis picture nikomatsakis  路  210Comments

withoutboats picture withoutboats  路  213Comments

alexcrichton picture alexcrichton  路  240Comments

nikomatsakis picture nikomatsakis  路  331Comments

thestinger picture thestinger  路  234Comments