doc: some peek improvements
#33265
doc: some peek improvements
#33265
Conversation
|
r? @brson (rust_highfive has picked a reviewer for you, use r? to override) |
| @@ -1031,17 +1031,15 @@ impl<I: ExactSizeIterator> ExactSizeIterator for Peekable<I> {} | |||
| impl<I: Iterator> Peekable<I> { | |||
| /// Returns a reference to the next() value without advancing the iterator. | |||
| /// | |||
| /// The `peek()` method will return the value that a call to [`next()`] would | |||
| /// return, but does not advance the iterator. Like [`next()`], if there is | |||
There was a problem hiding this comment.
Line removed for it was just repetition of the intro
There was a problem hiding this comment.
It's repeated for a reason; you may be looking at just the method's definition, and not the introduction.
There was a problem hiding this comment.
I don't understand... how does one look at doc body and not see the intro?
There was a problem hiding this comment.
Output isn't just for HTML, eventually we will have things like "look up this method on the command line", which many languages have and many people ask for.
There was a problem hiding this comment.
I expect that the intro is always going to appear... note that this is an intro for the method, not the module.
There was a problem hiding this comment.
Yes, it is the intro for the method. The method's docs should fully describe it, even if it's also discussed as part of the module itself, or the trait.
There was a problem hiding this comment.
Not sure we understand each other... in what cases will the doc for a method appear without its intro? By intro I mean the first line that appears in the doc for the method itself, in this case:
Returns a reference to the next() value without advancing the iterator.
There was a problem hiding this comment.
Ah ha, we are completely misunderstanding each other. So sorry! I agree with you here. I was confusing which part we were talking about; I thought you were concerned with repetition from the module-level or trait-level docs, not in the same doc bloc. And with these comments and the diff, I was confused.
Thank you for pushing back on this, I agree with you.
There was a problem hiding this comment.
I wish I could express meself better... I too often fail to find proper words to describe stuff.
There was a problem hiding this comment.
It's all good. This was entirely me, not you. (Well, and partially github)
On Jul 6, 2016, 17:56 -0400, Tshepang Lekhonkhobenotifications@github.com, wrote:
Insrc/libcore/iter/mod.rs(#33265 (comment)):
@@ -1031,17 +1031,15 @@ impl<I: ExactSizeIterator>ExactSizeIterator for Peekable{}>impl<I: Iterator>Peekable{>/// Returns a reference to the next() value without advancing the iterator.>///>- /// The
peek()method will return the value that a call to [next()] would>- /// return, but does not advance the iterator. Like [next()], if there isI wish I could express meself better... I too often fail to find proper words to describe stuff.
—
You are receiving this because you were mentioned.
Reply to this email directly,view it on GitHub(https://github.com/rust-lang/rust/pull/33265/files/e01e4cc4dbf657e411ecc16498e5f5c33d55f4d0#r69819098), ormute the thread(https://github.com/notifications/unsubscribe/AABsitkkqlKwXboovivMQ3Rvssi1aCKcks5qTCSZgaJpZM4ISXbk).
| /// assert_eq!(iter.peek(), Some(&&3)); | ||
| /// assert_eq!(iter.peek(), Some(&&3)); | ||
| /// | ||
| /// assert_eq!(iter.next(), Some(&3)); | ||
| /// | ||
| /// // after the iterator is finished, so is peek() | ||
| /// // After the iterator is finished, so is `peek` |
There was a problem hiding this comment.
please keep the ()s at the end of the function name
|
Sorry for missing this somehow! Thanks for this. Lots of good changes, but I disagree with removing the big block at the start. |
|
@tshepang ping! Can you please un-remove the first bit here so we can get this merged? |
|
You did not yet address my comment there |
|
@bors: r+ rollup |
|
📌 Commit db26b3f has been approved by |
doc: some `peek` improvements
No description provided.