Documentation snippets with ~~~ or ```

[gnzlbg]

The Rust book delimits documentation snippets for examples with ``` but ~~~ seems to work as well. Maybe we should have a new lint to tell people to use one over the other or at least to enforce a consistent stype within a crate.

E.g. this

/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let five = 5;
///
/// assert_eq!(6, add_one(5));
/// # fn add_one(x: i32) -> i32 {
/// #     x + 1
/// # }
/// ```
fn add_one(x: i32) -> i32 {
    x + 1
}

vs

/// Adds one to the number given.
///
/// # Examples
///
/// ~~~
/// let five = 5;
///
/// assert_eq!(6, add_one(5));
/// # fn add_one(x: i32) -> i32 {
/// #     x + 1
/// # }
/// ~~~
fn add_one(x: i32) -> i32 {
    x + 1
}

[mcarton]

Is there any difference between the two forms or is this yet another markdown way to write the same thing? The ````` style seems to be preferred, a lint to enforce consistency would be nice.

I also note that the current markdown lint should support ~~~ then.
Cc #1007.

[killercup]

From what I've seen, Rust documentation uses ```.

If this is added, it might be useful to also tell people to set the code block language (mentioned in #1007 as well). While rustdoc automatically sets the language to 'rust' for un-annotated code blocks, it should be preferred to be explicit (and to e.g. set "plain" to not highlight code blocks).

[steveklabnik]

Old Rust docs used to use ~~~, but I replaced them with ````` over time.

[gnzlbg]

Is the syntax ~~~ deprecated? If so we can just recommend using . Otherwise I don't know if it would be better to still recommend using or to recommend consistency independently of the style used (e.g. by inferring the style most commonly used within a crate).