Tracking issue for #[doc(alias = "...")]

[GuillaumeGomez]

Edit: Implemented in #49757. From the docs:

This feature allows you to add alias(es) to an item when using the rustdoc search through the doc(alias) attribute. Example:

#![feature(doc_alias)]
#[doc(alias = "x")]
#[doc(alias = "big")]
pub struct BigX;

Then, when looking for it through the rustdoc search, if you enter "x" or "big", search will show the BigX struct first.

[frewsxcv]

which pull request was this implemented in?

[GuillaumeGomez]

woups...

[sgrif]

I tried using this feature today, it doesn't appear to actually be implemented. I tried adding #[doc(alias = "...")] to multiple items, none of them showed up when searching for the alias, nor did they get added to search-index.js (where I assume they were supposed to live)

[sgrif]

Hm, it does appear to work for structs at least -- but not all items that otherwise appear in search. In particular it doesn't work on trait functions

[GuillaumeGomez]

Ah? Interesting. I'll need to take a look at what's generated.

[GuillaumeGomez]

As suggested here, I propose to stabilize this feature in order to make it usable outside of the std docs because of a few cases:

• crates with proc-macro can have their own syntax and might want to document it
• "overload" some items naming (for example in gtk-rs, since one of its dependencies has a Window type, we had to rename it GtkWindow but it'd make sense to have it with better ranking when looking for Window in the docs).

As for now, I don't see anything that could be an obstacle to stabilizing this feature?

@rfcbot fcp merge

[rfcbot]

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @QuietMisdreavus
• @kinnison
• @ollie27
• @onur

Concerns:

• associated-items resolved by Tracking issue for #[doc(alias = "...")] #50146 (comment)
• invalid-forms resolved by Tracking issue for #[doc(alias = "...")] #50146 (comment)
• naming resolved by Tracking issue for #[doc(alias = "...")] #50146 (comment)
• use-cases resolved by Tracking issue for #[doc(alias = "...")] #50146 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[GuillaumeGomez]

Considering that 2 out of the 3 members of the current rustdoc team approved, I guess it's good to go? Opening the PR then...

[ollie27]

Sorry about not getting back to this sooner.

What are some concrete use-cases for this? The GtkWindowExt example doesn't seem very compelling because searching for WindowExt already brings up GtkWindowExt.

@rfcbot concern use-cases

The name "alias" alone doesn't make it clear this affects only search. I can't think of anything better than #[doc(search_alias = "...")] or maybe #[doc(search_keyword = "...")] though.

@rfcbot concern naming

As pointed out by #50146 (comment) this doesn't yet work for associated items.

@rfcbot concern associated-items

Currently rustdoc is silently accepting things like:

#[doc(alias)]
#[doc(alias(0))]
#[doc(alias("foo"))]
#[doc(alias = 0)]

They have no effect but should of course be hard errors.

@rfcbot concern invalid-forms

[GuillaumeGomez]

The name "alias" alone doesn't make it clear this affects only search. I can't think of anything better than #[doc(search_alias = "...")] or maybe #[doc(search_keyword = "...")] though.

This is a fair point. I personally like the current one but if another wording seems better, all good for me (even though I don't like much "search_keyword").

Currently rustdoc is silently accepting things like:

I intended to add a lint for the case where the alias was discarded, which seemed like an idea solution. So I guess it'd wrap this as well.

As pointed out by #50146 (comment) this doesn't yet work for associated items.

#71724 should fix this problem.

What are some concrete use-cases for this? The GtkWindowExt example doesn't seem very compelling because searching for WindowExt already brings up GtkWindowExt.

No, it wasn't the best example. Here a better one: I discovered recently that adding aliases for C library bindings would be very helpful (which was my original point, but here's why). For example, you type the name of the C function and the alias shows you the rust equivalent. It'd be a big plus instead of having to grep through the source code.

[ollie27]

For example, you type the name of the C function and the alias shows you the rust equivalent. It'd be a big plus instead of having to grep through the source code.

Could you provide some links to crates which would benefit from this along the search terms that aren't producing useful results yet?

[tesuji]

It seems that this feature doesn't work with trait methods.

[GuillaumeGomez]

@ollie27 Litterally all C bindings. Sometimes, to improve the API, you have to rename things and call a few functions from the C library inside a same function. Or just the renaming might be confusing sometimes (it happened a lot for me when using rust-sdl2).

[GuillaumeGomez]

@lzutao doc alias tests seem to say the opposite. ;)

Maybe just try to update your nightly version?

[tesuji]

I've checked this feature again. It kinda works but I had to enter the whole (exact) aliasing keywords
for it to display in the search result.

• If entering an exact alias:
  

• If not:
  

I was using the latest nightly rustc.

[GuillaumeGomez]

@lzutao It's the expected behaviour: it only matches against the exact alias name.

[ollie27]

Sorry for the delay.

@rfcbot resolve use-cases

Sometimes, to improve the API, you have to rename things and call a few functions from the C library inside a same function. Or just the renaming might be confusing sometimes (it happened a lot for me when using rust-sdl2).

seems reasonable

@rfcbot resolve naming

I can't think of a better name.

@rfcbot resolve associated-items

Fixed by #71724

@rfcbot resolve invalid-forms

This is mostly done, only #75888 to go.

---

There is still a weird .replace("\"", "") that needs to be removed or a reason for it needs to be found:

rust/src/librustdoc/clean/types.rs

Line 665 in 3edf11c

.filter_map(|a| a.value_str().map(|s| s.to_string().replace("\"", "")))

I've noticed that #![doc(alias)] seems to be ignored when added to crate root. It might be worth making that work: #76298

It's the expected behaviour: it only matches against the exact alias name.

I'm not sure I agree with this. I personally would expect to be able to search for aliases the same way as everything else in the search index.

I'm not aware of any other reasons to block stabilizing this though.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.