rustdoc: Add stability and source links to the methods

[lifthrasiir]

Fixes #12932. This also fixes a span for the provided methods (originally excluded the method body), and provides an initial stylesheet for updated stability and source links ("better than nothing", adjustment and/or redesign welcomed). The rustdoc renders now look like this:

[lilyball]

Those source links are a bit glaring. I prefer the style seen by [src] links in the existing rustdoc (though I definitely approve of putting them on every item). You might also consider only showing them on hover, just to keep the visual clutter down.

I also think the stability annotations need some tweaking. I would suggest putting a little more space to the left, and perhaps ditching the underline in favor of e.g. [deprecated]. Also possibly drop the font size by a point or two.

[lifthrasiir]

I agree that the current layout is not that good (and that in general I suck at design ;), but it should be handled separately (there are lots of other issues in the rustdoc layout, I've noted some of them in #13804). My original intention is as follows:

• For the source links, I wanted to make it look like a button. We don't have a consistent design for links attached to the heading (unlike Haddock, say) so I've made an arbitrary design choice.
• For the stability indices, I wanted to make it look like a tag, and unlike the code. Personally I think that brackets without a further decoration can look like a code (especially for beginners).

[alexcrichton]

The implementation here looks great to me, nice work!

I think the only question here is style. I do agree that there's room for improvement. Perhaps some of the smaller things could be knocked out as part of this PR as well?

[huonw]

Do the stability attributes show their text yet?

e.g.

#[deprecated="use `bar`"]
pub fn foo() {}

#[experimental="use `foo`"]
pub fn bar() {}

(If you'll excuse my crappy library design ;P )

[lifthrasiir]

@alexcrichton What do you mean by smaller things? Something like #13804? (I'm totally willing to fix them, I wanted to make sure if that should be included in this PR.)

@huonw Not yet, except for the mouse-over title. Maybe "smaller things" can include that as well.

[alexcrichton]

Ah, by small things I mean some of @kballard's concerns. This looks ok to me, but I'm curious what @adrientetar thinks about it. Do you think there should be tweaks here and there to this?

[adrientetar]

I will look at this. @lifthrasiir: do you have a sample page at hand?

[lifthrasiir]

@adrientetar Sure, the current render as of 64d6178 is available at http://cosmic.mearie.org/2014/04/29-rustdoc/foo/struct.X.html.

[lifthrasiir]

While implementing the explicit stability documentation (as @huonw noted), I've also experimented with the position of the stability index and documentation if any. The resulting render, available at http://cosmic.mearie.org/2014/04/29-rustdoc2/foo/struct.X.html, looks not very bad either:

[lilyball]

I don't like that. It's reducing information density even further, which is a bad idea given the current state of the documentation. I'm also concerned about how this will look when the functions actually have docstrings.

I think the stability attribute should stay on the same line as the function signature. Perhaps the stability message could only show up when you hover over the attribute? (and put some indicator on the attribute to indicate that it has a hover).

[adrientetar]

I'm working on this, will follow-up tomorrow. My working branch is adrientetar/lift-rustdoc.

[lifthrasiir]

@adrientetar Thank you! I think you've already rebased my initial commits; should I close this issue in favor of #14042?

[adrientetar]

@lifthrasiir Yes, otherwise it will close it when merged.