Skip to content

add documentation for the while keyword #60761

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions src/libstd/keyword_docs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -558,6 +558,28 @@ mod impl_keyword { }
/// [Reference]: ../reference/statements.html#let-statements
mod let_keyword { }

#[doc(keyword = "while")]
//
/// while loop
///
/// `while` is used to define while loops in Rust. It runs the code inside it
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please write this in a way that is not a tautology ("the while keyword is used to define a while loop"). It is true but not meaningful.

/// until the condition in the while loop becomes False or there the code uses
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Capitalization: false is a lowercase noun. This looks like muscle memory from Python. ;)

Copy link
Contributor

@czipperz czipperz May 24, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably should also use an inline code block (back ticks) around false

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"until the condition becomes false" is meaningful English without backticks. I think adding backticks would detract in this case.

/// `break`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

until [...] there the code uses break.

This "until there" part of the sentence sounds wrong to me. Not clear what "there" is referring to.

///
///
/// ```rust
/// let mut i = 0;
/// while i > 10 {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 is not > 10 so this loop would never run -- seems unintentional.

/// println!("i is {}", i);
/// i += 1;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please come up with a different example where while is the best solution. The point of example code is usually not showing how to write something. The point is showing why you would want to write the thing. This code shows a while loop but if you were solving the problem that this code is solving then you would not want to use a while loop. That makes the example not compelling.

/// }
/// ```
///
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page should cover while let as well.

/// For more information on `while` and loops in general, see the [Reference].
///
/// [Reference]: ../reference/expressions/loop-expr.html
mod while_keyword { }

#[doc(keyword = "loop")]
//
/// The loop-defining keyword.
Expand Down