Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
GuillaumeGomez opened this issue Apr 21, 2018 · 21 comments · Fixed by #75740
Closed

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

GuillaumeGomez opened this issue Apr 21, 2018 · 21 comments · Fixed by #75740
Assignees
Labels
A-doc-alias B-unstable C-tracking-issue disposition-merge finished-final-comment-period T-rustdoc

Comments

@GuillaumeGomez
Copy link
Member

@GuillaumeGomez GuillaumeGomez commented Apr 21, 2018

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.

@GuillaumeGomez GuillaumeGomez added the T-rustdoc label Apr 21, 2018
@GuillaumeGomez GuillaumeGomez self-assigned this Apr 21, 2018
@frewsxcv
Copy link
Member

@frewsxcv frewsxcv commented Apr 23, 2018

which pull request was this implemented in?

@GuillaumeGomez
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented Apr 23, 2018

@QuietMisdreavus QuietMisdreavus added the C-tracking-issue label May 15, 2018
@GuillaumeGomez

This comment has been minimized.

@petrochenkov

This comment has been minimized.

@petrochenkov petrochenkov reopened this Nov 1, 2018
@sgrif
Copy link
Contributor

@sgrif sgrif commented May 28, 2019

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
Copy link
Contributor

@sgrif sgrif commented May 28, 2019

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
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented May 29, 2019

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

@GuillaumeGomez
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented Nov 26, 2019

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
Copy link

@rfcbot rfcbot commented Nov 26, 2019

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

Concerns:

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.

@rfcbot rfcbot added proposed-final-comment-period disposition-merge labels Nov 26, 2019
@jonas-schievink jonas-schievink added the B-unstable label Nov 26, 2019
@GuillaumeGomez
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented Apr 28, 2020

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
Copy link
Member

@ollie27 ollie27 commented Apr 30, 2020

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
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented Apr 30, 2020

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
Copy link
Member

@ollie27 ollie27 commented May 2, 2020

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?

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue May 15, 2020
…ts, r=ollie27

Doc alias improvements

After [this message](rust-lang#50146 (comment)), I realized that the **doc alias**. So this PR does the followings:

 * Align the alias discovery on items added into the search-index. It brings a few nice advantages:
   * Instead of cloning the data between the two (in rustdoc source code), we now have the search-index one and aliases which reference to the first one. So we go from one big map containing a lot of duplicated data to just integers...
 * In the front-end (main.js), I improved the code around aliases to allow them to go through the same transformation as other items when we show the search results.
 * Improve the search tester in order to perform multiple requests into one file (I think it's better in this case than having a file for each case considering how many there are...)
    * I also had to add the new function inside the tester (`handleAliases`)

Once this PR is merged, I intend to finally stabilize this feature.

r? @ollie27

cc @rust-lang/rustdoc
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue May 15, 2020
…ts, r=ollie27

Doc alias improvements

After [this message](rust-lang#50146 (comment)), I realized that the **doc alias**. So this PR does the followings:

 * Align the alias discovery on items added into the search-index. It brings a few nice advantages:
   * Instead of cloning the data between the two (in rustdoc source code), we now have the search-index one and aliases which reference to the first one. So we go from one big map containing a lot of duplicated data to just integers...
 * In the front-end (main.js), I improved the code around aliases to allow them to go through the same transformation as other items when we show the search results.
 * Improve the search tester in order to perform multiple requests into one file (I think it's better in this case than having a file for each case considering how many there are...)
    * I also had to add the new function inside the tester (`handleAliases`)

Once this PR is merged, I intend to finally stabilize this feature.

r? @ollie27

cc @rust-lang/rustdoc
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue May 15, 2020
…ts, r=ollie27

Doc alias improvements

After [this message](rust-lang#50146 (comment)), I realized that the **doc alias**. So this PR does the followings:

 * Align the alias discovery on items added into the search-index. It brings a few nice advantages:
   * Instead of cloning the data between the two (in rustdoc source code), we now have the search-index one and aliases which reference to the first one. So we go from one big map containing a lot of duplicated data to just integers...
 * In the front-end (main.js), I improved the code around aliases to allow them to go through the same transformation as other items when we show the search results.
 * Improve the search tester in order to perform multiple requests into one file (I think it's better in this case than having a file for each case considering how many there are...)
    * I also had to add the new function inside the tester (`handleAliases`)

Once this PR is merged, I intend to finally stabilize this feature.

r? @ollie27

cc @rust-lang/rustdoc
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue May 16, 2020
…ts, r=ollie27

Doc alias improvements

After [this message](rust-lang#50146 (comment)), I realized that the **doc alias**. So this PR does the followings:

 * Align the alias discovery on items added into the search-index. It brings a few nice advantages:
   * Instead of cloning the data between the two (in rustdoc source code), we now have the search-index one and aliases which reference to the first one. So we go from one big map containing a lot of duplicated data to just integers...
 * In the front-end (main.js), I improved the code around aliases to allow them to go through the same transformation as other items when we show the search results.
 * Improve the search tester in order to perform multiple requests into one file (I think it's better in this case than having a file for each case considering how many there are...)
    * I also had to add the new function inside the tester (`handleAliases`)

Once this PR is merged, I intend to finally stabilize this feature.

r? @ollie27

cc @rust-lang/rustdoc
@tesuji
Copy link
Contributor

@tesuji tesuji commented May 26, 2020

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

@GuillaumeGomez
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented May 30, 2020

@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
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented May 30, 2020

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

Maybe just try to update your nightly version?

@tesuji
Copy link
Contributor

@tesuji tesuji commented May 31, 2020

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:
    image

  • If not:
    image

I was using the latest nightly rustc.

Manishearth added a commit to Manishearth/rust that referenced this issue Jun 22, 2020
@GuillaumeGomez
Copy link
Member Author

@GuillaumeGomez GuillaumeGomez commented Jun 22, 2020

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

Manishearth added a commit to Manishearth/rust that referenced this issue Jun 22, 2020
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Jun 23, 2020
Manishearth added a commit to Manishearth/rust that referenced this issue Jun 23, 2020
Manishearth added a commit to Manishearth/rust that referenced this issue Jun 23, 2020
@ollie27
Copy link
Member

@ollie27 ollie27 commented Sep 3, 2020

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:

.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 rfcbot added the final-comment-period label Sep 3, 2020
@rfcbot
Copy link

@rfcbot rfcbot commented Sep 3, 2020

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

@rfcbot rfcbot removed the proposed-final-comment-period label Sep 3, 2020
@rfcbot rfcbot added finished-final-comment-period and removed final-comment-period labels Sep 13, 2020
@rfcbot
Copy link

@rfcbot rfcbot commented Sep 13, 2020

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.

@rfcbot rfcbot added the to-announce label Sep 13, 2020
@spastorino spastorino removed the to-announce label Sep 16, 2020
@jyn514 jyn514 added the A-doc-alias label Sep 27, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-doc-alias B-unstable C-tracking-issue disposition-merge finished-final-comment-period T-rustdoc
Projects
None yet
Development

Successfully merging a pull request may close this issue.