Lint non-code syntax for variables in documentation comments

[gnzlbg]

Here:

/// This function adds a with `b`.
fn add(a: u32, b: u32) -> u32 { a + b };

note how in the documentation comment 'b' is quoted but a is not. We should lint about these.

[oli-obk]

Your example is the one that's the most impossible... a is an english word.

We'd be getting false positives left and right even if we'd have some english language parser. Not really sure if we can act on this. Maybe somebody's got ideas how to do it.

[gnzlbg]

Your example is the one that's the most impossible... a is an english word.

Indeed.

How do Rust IDEs infer what variables do?

For example in C++ there is the Doxygen format which IDEs use it to give detailed descriptions of the arguments and return type, something like:

/// Adds two values. 
///
/// Long description.
///
/// # Arguments
///
/// - `T`: type of the arguments to add
/// - `a`: argument to add
/// - `b`: argument to add
///
/// # Returns
///
/// Sum of `a` and `b`.
///
/// # Panics
///
/// If the sum of `a` and `b` overflows.
///
/// # Complexity
/// 
/// - time: O(1) 
/// - space: O(1)
fn add<T>(a: T, b: T) -> T;

[oli-obk]

I'd really want to have

fn add<T>(
    /// super first argument
    a: T,
    /// horrible second argument
    b: T,
/// Returns sum of `a` and `b`
) -> T;

Maybe I'll do an rfc next year

[gnzlbg]

@oli-obk we should ping the new rustdoc repo on this as well. It might be easier to prototype this there than in the old rustdoc.

[killercup]

@gnzlbg cf #1007 (comment) re: doc format