rustdoc should handle impls differently

[brson]

Now that they are not named items, rustdoc should probably, beneath each type, have a section for the inherent methods and a section for implemented traits.

[catamorphism]

Nominating for milestone 4 (well-covered).

[graydon]

just a bug, removing milestone/nomination.

[catamorphism]

Bug triage. Should still be fixed.

[emberian]

#8125

Fixed by rustdoc_ng

[orenbenkiki]

I like the fact I can write in my file:

/// Description of some group of functions (which isn't a trait).
impl MyType { ... }

#[test]
fn test_some_funcs() { ... }

/// Description of some other group of functions.
impl MyType { ... }

#[test]
fn test_more_funcs() { ... }

And then get in rustdoc to see each section separately as:

impl for MyType - Description of some group of functions (which isn't a trait).
impl for MyType - Description of some other group of functions.

This makes both the documentation and the source code more approachable, as each section has its own description and list of functions. The only problem is that rustdoc links all these sections in the index to the first one, which IMO is a bug.

Of course, any other way to group functions together in a section with description in the documentation would be fine, but this one seems pretty natural... what's the equivalent of the above in rustdoc-ng?

[emberian]

@orenbenkiki the above works just fine as-is, and will be rendered similarly on the trait page.

[emberian]

Now that rustdoc_ng has been merged, closing.

[orenbenkiki]

As long as the links to the sections would work - right now (in rustdoc) the anchor for impl MyType is simply implementation-for-MyType. This means if there's more than one, all the anchors and links are the same, and therefore the browser will always jump to the same (first) one, regardless on which one was clicked.

To fix that there would need to be some sequential index attached to each anchor (that is, implementation-for-My-Type-1, implementation-for-MyType-2, ...). Probably only attach the index for the 2nd link and onward, so that if there's only one entry the anchor will stay clean.

In principle this needs to be fixed in rustdoc. I guess I'll have to wait until rustdoc_ng will actually generate HTML to see if the problem will also exist there....

[huonw]

@orenbenkiki you can see what the output is like here: http://seld.be/rustdoc/master/std/index.html

[orenbenkiki]

Oh, right. Hmmm - I don't see an example of the pattern I posed above anywhere. I use it in my code, though... I just pulled the latest head - what flags do I need to give rustdoc_ng to generate HTML it would generate for my project, so I can see how it would look like? The --help flag isn't very helpful at the moment.

[orenbenkiki]

Ok, installed node, npm, rustdoc_web, run rustdoc on my code, looked at both the HTML and the JSON output...

It seems that rustdoc_ng does emit the required data (that is, the documentation of the separate impl sections) into the JSON file. However, the rustdoc_web completely ignores it, and there are no traces of it in the generated HTML.

So, in this respect, rustdoc_ng is worse than rustdoc - rustdoc has a bug in generating the correct links, but it at least generates the separate sections with the documentation and list of functions in each one...