Missing documentation for `inline` attribute

What it does

We work in a performance sensitive domain and so occasionally require the use of #[inline(always)] and #[inline(never)]. However, we don't want to second-guess the compiler except when absolutely necessary (specially with PGO builds). Ideally we would like to have a lint that forces a doc comment (similar to missing_safety_doc for unsafe functions) explaining why the particular inline attribute is required. Something like an /// Inline: <explanation> would work (or alternatively an /// # Inline header similar to /// # Safety).

I understand this is a non-standard use-case, but we were not able to find a way to add a custom lint to clippy easily. If this is not an acceptable lint, would it be possible to point us to a way we can add a custom lint ourselves?

Lint Name

missing_inline_doc

Category

suspicious, style, perf, pedantic

Advantage

• Better documentation of why the inline attribute is required for a particular function

Drawbacks

Use of non-standard /// Inline: doc comment

Example

#[inline(always)]
fn very_large_hot_function() {
    [ ... ]
}

Could be written as:

/// Inline: This function is very large, so the PGO skips inlining, but we have seen performance improvements if we always inline this function.
/// See performance results at: <link-to-performance-results>
#[inline(always)]
fn very_large_hot_function() {
    [ ... ]
}

Start by reviewing Clippy's existing missing_safety_doc lint and the way custom lints are added. Determine how an inline attribute and its surrounding documentation would be identified, then define tests covering #[inline(always)] and #[inline(never)] with and without an explanation; done means the proposed missing_inline_doc behavior and documentation are agreed and tested.