rustdoc: Add doc snippets for trait impls, with a read more link #33679
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Added support for a fallback to short docs The following code produces the pictured docs: pub struct Foo<'a>(&'a str);
impl<'a> Iterator for Foo<'a> {
type Item = &'a str;
fn next(&mut self) -> Option<&'a str> {
Some(self.0)
}
/// All your docs are
///
/// belong to us
fn size_hint(&self) -> (usize, Option<usize>) {
(1,None)
}
}
Note that the show more link isn't shown on |
|
The formatting for "read more" could probably be improved, suggestions? |
|
Why have the +/- expand box and "read more"? Why not show all the description, but have it hidden by default? |
|
That's another option, I guess. Is there anything else we collapse by default? |
|
@Manishearth How about putting "Read more" on the same line to save space? "Consumes the iterator, returning the last element. More..." |
|
That can work. I didn't do it because it requires some markdown splicing, but that's no big deal |
|
I don't have a preference of any one of the suggestions -- @alexcrichton, do you? Both are easy to implement. |
I like it. @Manishearth: How do you know it's only one line? |
That's how the snippet function works |
I guess it's based on the characters' number. I don't really like this if this is really the case. |
|
I don't know what you mean? I think it just extracts the first line, in a markdown-aware way. It's already used for documenting modules and in search results |
|
I thought you said that if the description was only one short line, no need to hide it. And I was wondering how you decided if it was short. |
|
I don't decide if it's short. The heuristic is if it's a single line, I don't show a "Read more" link - See https://github.com/rust-lang/rust/pull/33679/files#diff-05c3c8b7c08a25764218b8c18d8204b7R1672 |
|
@Manishearth yeah I like @pcwalton's suggestion of placing the link on the same line to cut down on space (that's why these links were omitted in the first place). Also, could you build libstd docs and provide a link so we can browse around as well? It'd probably help to see what this look like in practice as well. Nice idea though! |
|
Perhaps the "read more" could be expanded in-place instead of linking to another page? |
Manishearth
force-pushed
the
rustdoc-readmore-impls
branch
from
b78025f
to
74633b0
Compare
|
@Manishearth: Like this it's just great! Thanks a lot for this! |
|
Looks good to me! Can you also add a test to ensure that the longer form docs are omitted? That is, if there's multiple lines, none but the first show up in the output |
|
Done |
Manishearth
force-pushed
the
rustdoc-readmore-impls
branch
2 times, most recently
from
24502d3
to
da15112
Compare
|
@bors: r+ da15112c825beb8792ab9a26c8d033c1d7bbc0d3 |
|
⌛ Testing commit da15112 with merge 7c4159c... |
|
💔 Test failed - auto-linux-64-opt-rustbuild |
|
Ah, that was a legit error, I wasn't ignoring static methods for Deref. There are a bunch of failures for internals docs though (haven't investigated yet, it could just be this bug) |
Manishearth
force-pushed
the
rustdoc-readmore-impls
branch
from
da15112
to
9ce018b
Compare
|
Fixed. the internals errors listed above still exist |
Manishearth
added a commit
to Manishearth/rust
that referenced
this pull request
May 21, 2016
… r=alexcrichton rustdoc: Add doc snippets for trait impls, with a read more link The read more link only appears if the documentation is more than one line long.  It currently does not appear on non-defaulted methods, since you can document them directly. I could make it so that default documentation gets forwarded if regular docs don't exist. Fixes rust-lang#33672 r? @alexcrichton cc @steveklabnik
bors
added a commit
that referenced
this pull request
May 21, 2016
|
Would it be possible to override this with impl-specific documentation for methods? (Is there already an issue for that?) EDIT: Aha. I was only looking at stable, where this wasn't yet the case. |
|
This already happens |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The read more link only appears if the documentation is more than one line long.
It currently does not appear on non-defaulted methods, since you can document them directly. I could make it so that default documentation gets forwarded if regular docs don't exist.
Fixes #33672
r? @alexcrichton
cc @steveklabnik