New lint: documenting types’ generic parameters

What it does

Detects when a type visible outside the crate (and not doc(hidden)) has a generic parameter of any kind (type parameter, lifetime parameter, or const generic parameter), and neither the documentation string nor the public fields’ types mention that parameter.

Advantage

Structs with private fields can have generic parameters that are used in ways that are very difficult to understand from only the information available automatically in documentation. This can significantly interfere with using a library when it becomes necessary to write down a concrete type name, especially if that type is typically used without naming it (e.g. in a method chain) so there are no working examples to hand.

Ideally, this would be a pedantic lint (like other missing_*_doc lints) because its purpose is to make library authors who are concerned with providing a good API think about documenting things that it may not be obvious aren’t obvious to the new documentation reader.

Drawbacks

• Sometimes the use is very obvious, like a single lifetime parameter on a struct which is only ever created by borrowing something.
• Sometimes the parameter is, or could be, given a name that, in context, communicates everything that needs to be said.

In those cases, requiring documentation would not have very much value and might lead to redundant boilerplate documentation that’s not a good use of the reader’s or the writer’s time.

To minimize the degree to which this encourages boilerplate, the lint should accept appearances of the name anywhere in the text (not e.g. only within a # Generic parameters section), as long as it is somewhere inside code formatting (that is not a doc-test?), even if that code element contains other text too. This gives many opportunities for the parameter explanation to be worked into text that needs to be written anyway.

Example

/// Blah blah blah some made-up concepts you, the documentation reader,
/// don't have context to understand yet blah blah blah.
pub struct Borrower<'r, 'ctx, T> {
    foo: &'r Thingy<'ctx, T>,     // Remember, this does not appear in documentation!
}

Could be written as:

/// Blah blah blah some made-up concepts you, the documentation reader,
/// don't have context to understand yet blah blah blah.
///
/// `'r` is the lifetime for which the `Thingy<'ctx, T>` from which this
/// was created will be borrowed.
pub struct Borrower<'r, 'ctx, T> {
    foo: &'r Thingy<'ctx, T>,
}

Start by reviewing Clippy's existing missing_*_doc lints and the behavior described in the issue's Rust examples. Trace how lint applicability and documentation text are analyzed before deciding how type, lifetime, and const parameters should be recognized. Done means the proposed lint handles public visible types, excluded hidden items, public field types, and documented code-formatted parameter names as specified.