Improve associated constant rendering in rustdoc

[GuillaumeGomez]

Before:

After:

cc @SergioBenitez

r? @rust-lang/docs

[frewsxcv]

LGTM. Gonna hold off on doing an r+ to see if others have feedback.

[SergioBenitez]

Definitely nicer! My only remaining concern is that long definitions still look quite bad. As an example, see ContentType::JSON. If the definition remains on the same line as the name of the constant, the rendering won't look great.

To ameliorate this, I propose that we adopt one of the following:

1. Hide the definition entirely on the main page. Clicking on the constant's name leads to a page that shows the full definition as well as the documentation.
2. Hide the definition by default but allow users to click an "expand" button to see the definition.
3. Perhaps in conjunction with 2, move the definition to the body of the documentation, where the docstring is shown. Place the definition inside of a shaded pre section.

[GuillaumeGomez]

I feel a bit off for hiding type and value information by default. In your case, the indent will allow to make the reading easier (which is helped by the new style).

[steveklabnik]

Seems good to me too.

[QuietMisdreavus]

Not quite a fan, but probably better than nothing. I like @SergioBenitez's suggestion 3, though I'm not sure how rustdoc receives the values of associated consts. It might take some finesse (read: duplicate code) to get it to render through the same pretty-print as a struct's definition.

[GuillaumeGomez]

I just thought that moving associated consts in a "category" of their own might be problematic in case this value is only for certain implementation (I think about type parameters specialization).

[SergioBenitez]

That's not what I'm proposing, @GuillaumeGomez. Keep the const documentation where it is, relatively, but make it look like:

const Other: usize

const Other: usize = 12

This is the documentation for this item.

A larger example:

const Any: ContentType

const Any: ContentType = ContentType{ttype: UncasedAscii{string: Cow::Borrowed("*"),},
           subtype: UncasedAscii{string: Cow::Borrowed("*"),},
           params: None,}

ContentType representing any Content-Type (*/*).

You can play with the formatting and optionally hide the definition by default.

[GuillaumeGomez]

Ok, sorry the misunderstanding! This way seems to be quite good indeed. I'll give it a try.

[GuillaumeGomez]

Ok, I updated as suggested:

Hidden:

Not hidden:

By default they're visible.

[SergioBenitez]

@GuillaumeGomez I think we still want to know the type in the non-hidden version, right?

[frewsxcv]

Looking great @GuillaumeGomez, nice job :)

[SergioBenitez]

Actually, if the definition is visible by default, maybe it's okay to not include the type in the hidden version?

[GuillaumeGomez]

I'll need to add tests as well.

[GuillaumeGomez]

So, I added all missing types in the "correct" output and added tests (and filed an ICE, so nice of me).

[steveklabnik]

@SergioBenitez what do you think?

[frewsxcv]

@bors r+

[bors]

📌 Commit bd704ba has been approved by frewsxcv

[bors]

⌛ Testing commit bd704ba with merge 9b19645...

[frewsxcv]

@bors retry

[bors]

⌛ Testing commit bd704ba with merge f7cc0c6...

[alexcrichton]

@bors: retry

Looks like travis missed this PR...