Update doctest in comments.md

[chucksmash]

For a user following the path of reading Chapter 5: Syntax & Symantics
prior to Chapter 4: Learn Rust, this will be the first time they have
encountered executable tests inside documentation comments.

The test will fail because the add_one function is not defined in
the context of the doctest. This might not be the optimal place to
introduce and explain the /// # notation but I think it is important
that this snippet pass as a test when rustdoc --test is run against
it.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @alexcrichton (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[alexcrichton]

I think that because doctests are idiomatically shown as examples for library documentation it may make more sense to show the example of importing the add_one function instead of redefining it. Perhaps something like:

/// ```
/// use krate::add_one;
///
/// let five = 5;
/// assert_eq!(6, add_one(five));
/// ```

[steveklabnik]

@alexcrichton that has the unfortunate property of turning an executable test into a non-executable test

[steveklabnik]

@chucksmash I agree with you about the small concern regarding the # syntax. But for now, this is a strict improvement, so let's do it.

[steveklabnik]

@bors: r+ rollup

[bors]

📌 Commit 675b3de has been approved by steveklabnik