Suggest `#[doc(alias(...))]` attribute

What it does

This lint suggests adding the attribute #[doc(alias(...))] for functions that "redirect" the arguments to another function and the function that is redirected to.

For example:

pub fn print(name: &str, value: usize) -> i32 {
    println!("name: {}: value: {}", name, value);
    42
}

pub fn hello(name: &str, value: usize) -> i32 {
    print(name, value)
}

here the hello function is just another "name" for the print function, so one should add the doc alias attribute:

#[doc(alias("hello"))]
pub fn print(name: &str, value: usize) -> i32 {
    println!("name: {}: value: {}", name, value);
    42
}

#[doc(alias("print"))]
pub fn hello(name: &str, value: usize) -> i32 {
    print(name, value)
}

See documentation of the attribute:
https://doc.rust-lang.org/rustdoc/advanced-features.html#add-aliases-for-an-item-in-documentation-search

Categories (optional)

• Kind: clippy::pedantic

What is the advantage of the recommended code over the original code?

Easier to find functions that are aliases and makes this feature more discoverable/more people would use it.

Drawbacks

Might be too complex or could cause a lot of false positives?

For now, I would restrict it to obvious cases like:

// must not be called on a field of the struct!
Self::<some function name>( $(args)* )

Example

Some may argue that this would be "bad" design, because you essentially have two functions that do the exact same thing.
So here is an example where I am currently using it:

use core::hash::BuildHasher;
use core::marker::PhantomData;

pub struct HashMap<K, V, B: BuildHasher> {
    _p: PhantomData<(K, V)>,
    _build_hasher: B,
}

impl<K, V, B: BuildHasher> HashMap<K, V, B> {
    // this is what the function is called in the standard library
    // which might be very confusing, because there exists the `Hasher`
    // trait, which is not accepted here!
    pub fn with_hasher(hasher: B) -> Self {
        unimplemented!()
    }

    pub fn with_build_hasher(hasher: B) -> Self {
        unimplemented!()
    }
}

fn main() {}

Could be written as:

use core::hash::BuildHasher;
use core::marker::PhantomData;

pub struct HashMap<K, V, B: BuildHasher> {
    _p: PhantomData<(K, V)>,
    _build_hasher: B,
}

impl<K, V, B: BuildHasher> HashMap<K, V, B> {
    // this is what the function is called in the standard library
    // which might be very confusing, because there exists the `Hasher`
    // trait, which is not accepted here!
    #[doc(alias("with_build_hasher"))]
    pub fn with_hasher(hasher: B) -> Self {
        unimplemented!()
    }

    // so this would be a very valid reason to add an alias function that essentially does the same thing
    // to keep compatibility with the standard library
    #[doc(alias("with_hasher"))]
    pub fn with_build_hasher(hasher: B) -> Self {
        unimplemented!()
    }
}

fn main() {}

No source files, tests, or implementation entry points are named. Start by reviewing the proposed forwarding-function cases and the linked rustdoc alias documentation; done means an agreed lint can identify only sufficiently obvious redirects and recommend matching #[doc(alias(...))] attributes without excessive false positives.