Rustdoc: example of use of assertions

[Songbird0]

I added this section at the beginning of the file because it seems to be basic information. Let me know if there's someplace more relevant.

See #47945.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (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. Due to 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.

[QuietMisdreavus]

Hmm, i'm not a fan of this phrasing. How about something like this?

Passing or failing a doctest

Like regular unit tests, regular doctests are considered to "pass" if they compile and run without panicking. So if you want to demonstrate that some computation gives a certain result, the assert! family of macros works the same as other Rust code:

let foo = "foo";

assert_eq!(foo, "foo");

This way, if the computation ever returns something different, the code panics and the doctest fails.

---

Also, be aware that we like to insert hard line breaks into the docs to keep a single line from running longer than 100 characters. You can use the other sections in this file as a guideline.

[Songbird0]

I'll replace the changes.

Also, be aware that we like to insert hard line breaks into the docs to keep a single line from running longer than 100 characters. You can use the other sections in this file as a guideline.

Understood.

[QuietMisdreavus]

Thanks so much! It looks great now. I'll let travis run its course and push this on if it turns green. (Unless @steveklabnik or @GuillaumeGomez have farther comments before then.)

[GuillaumeGomez]

Nope, looks good to me. But a squash is required here as well. :)

[Songbird0]

The squash was performed, here, @GuillaumeGomez.

[GuillaumeGomez]

Thanks!

@bors: r+ rollup

[bors]

📌 Commit a48224b has been approved by GuillaumeGomez