doc(alias) is stable and it's gonna be super useful!

Since Rust 1.48, #[doc(alias = "...")] is now stable. Let's see what it might change and improve!

What is it?

As described in the Rust release blog post, you can add aliases on items. For example:

Run#[doc(alias = "Foo")]
pub struct Bar;

So when you'll look for "Foo" in the documentation using the search input, Bar will show up. Nice add but you're not sure to see why it's so useful, right? That's where FFI binding crates come in!

Aliases to improve FFI search

Now, let's say you're using a binding over some dark C libraries providing the following functions:

void *some_dark_c_library_init();
void some_dark_c_library_release(void *lib_instance);
void some_dark_c_library_do_that_stuff(void *lib_instance);

The binding might look like this:

Runpub struct DarkCLibrary(*mut void);

impl DarkCLibrary {
    pub fn init() -> Option<Self> {
        let ptr = unsafe { ffi::some_dark_c_library_init() };
        if ptr.is_null() { return None; }
        Some(Self(ptr))
    }

    pub fn do_that_stuff(&self) {
        unsafe { ffi::some_dark_c_library_do_that_stuff(self.0) }
    }
}

impl Drop for DarkCLibrary {
    fn drop(&mut self) {
        unsafe { ffi::some_dark_c_library_do_that_stuff(self.0) }
    }
}

Ok, so now, let's say you don't know where to start and try to search for "some_dark_c_library_init". Obvisouly, very little chances to find what you're looking for! Now let's update the init function:

Run#[doc(alias = "some_dark_c_library_init")]
pub fn init() -> Option<Self> {
    let ptr = unsafe { ffi::some_dark_c_library_init() };
    if ptr.is_null() { return None; }
    Some(Self(ptr))
}

Now, when you'll look for "some_dark_c_library_init", DarkCLibrary::init will show up! At this point, I think you understand where I want to go and why it's gonna be awesome.

Using it as operator alias

Another use case that we came up with are operators. For example, we added aliases for all operators in the std library! So for example, if you search for != in the std documentation, you'll find the Eq and PartialEq traits! So it's definitely possible to use it in even more cases (I'm looking at you nalgebra ;) - It's an awesome library, you should use it if you need to do mathematic computations!). A little screenshot of what it looks like in the std:

Any other use case?

Actually yes! It's similar to FFI aliases but extending it to other programming languages "common functions". For example, providing aliases for "printf"/"console.log"/"echo" or equivalent to our print!/println! macros would be very useful. And actually, some pull requests adding such things have already been opened to the std:

• Add the "memcpy" doc alias to slice::copy_from_slice
• Add "memset" as doc alias to slice::fill()
• Add doc aliases for print macros
• Add the "async" and "promise" doc aliases to `core::future::Future`
• Add doc aliases for memory allocations

Conclusion

doc(alias) isn't a big feature or a game-changer in itself, however it now allows to greatly improve documentation search in multiple contexts.

For example, gtk-rs plan to add it soon (I'll implement it in the next days) so that next release will have much better documentation!

In hope that all other crates will also add it too (and you, readers, can help so don't hesitate!).

See you around!