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

rustdoc-search: add support for nested generics #109802

Merged

Conversation

notriddle
Copy link
Contributor

@notriddle notriddle commented Mar 31, 2023

This change allows search.js to parse nested generics (which look Like<This<Example>>) and match them. It maintains the existing "bag semantics", so that the order of type parameters is ignored but the number is required to be greater than or equal to what's in the query.

For example, a function with the signature fn read_all(&mut self: impl Read) -> Result<Vec<u8>, Error> will match these queries:

  • Read -> Result<Vec<u8>, Error>
  • Read -> Result<Error, Vec>
  • Read -> Result<Vec<u8>>

But it does not match Result<Vec, u8> or Result<u8<Vec>>.

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Mar 31, 2023
@rustbot
Copy link
Collaborator

rustbot commented Mar 31, 2023

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @Folyd, @jsha

@GuillaumeGomez
Copy link
Member

It will need an FCP. Also, could you update the documentation and the help in the rustdoc pages to include this please?

@notriddle
Copy link
Contributor Author

@GuillaumeGomez I added a description of generic-matching semantics to the rustdoc book.

The ? button doesn't mention generics at all, and I'm not sure there's need to add it, but I did find a mistake in there and will open a separate pull request to update it.

@notriddle
Copy link
Contributor Author

@rfcbot fcp merge

@rfcbot
Copy link

rfcbot commented Mar 31, 2023

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

No concerns currently listed.

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 Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. and removed proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. labels Mar 31, 2023
@rfcbot
Copy link

rfcbot commented Apr 4, 2023

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

@bors
Copy link
Contributor

bors commented Apr 14, 2023

☔ The latest upstream changes (presumably #110324) made this pull request unmergeable. Please resolve the merge conflicts.

@rfcbot rfcbot added finished-final-comment-period The final comment period is finished for this PR / Issue. and removed final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. labels Apr 14, 2023
@rfcbot
Copy link

rfcbot commented Apr 14, 2023

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.

This will be merged soon.

@rfcbot rfcbot added the to-announce Announce this issue on triage meeting label Apr 14, 2023
@notriddle notriddle force-pushed the notriddle/rustdoc-search-generics-nested branch from 4066981 to 6ce5327 Compare April 14, 2023 21:55
@GuillaumeGomez
Copy link
Member

r=me once CI pass

@notriddle
Copy link
Contributor Author

@bors r=GuillaumeGomez rollup

@bors
Copy link
Contributor

bors commented Apr 14, 2023

📌 Commit 6ce5327 has been approved by GuillaumeGomez

It is now in the queue for this repository.

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Apr 14, 2023
@bors
Copy link
Contributor

bors commented Apr 15, 2023

⌛ Testing commit 6ce5327 with merge 3312a30...

@bors
Copy link
Contributor

bors commented Apr 15, 2023

☀️ Test successful - checks-actions
Approved by: GuillaumeGomez
Pushing 3312a30 to master...

@bors bors added the merged-by-bors This PR was explicitly merged by bors. label Apr 15, 2023
@bors bors merged commit 3312a30 into rust-lang:master Apr 15, 2023
@rustbot rustbot added this to the 1.70.0 milestone Apr 15, 2023
@notriddle notriddle deleted the notriddle/rustdoc-search-generics-nested branch April 15, 2023 13:59
@rust-timer
Copy link
Collaborator

Finished benchmarking commit (3312a30): comparison URL.

Overall result: no relevant changes - no action needed

@rustbot label: -perf-regression

Instruction count

This benchmark run did not return any relevant results for this metric.

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

mean range count
Regressions ❌
(primary)
- - 0
Regressions ❌
(secondary)
- - 0
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
-5.5% [-5.5%, -5.5%] 1
All ❌✅ (primary) - - 0

Cycles

This benchmark run did not return any relevant results for this metric.

@apiraino apiraino removed the to-announce Announce this issue on triage meeting label Apr 20, 2023
bors added a commit to rust-lang-ci/rust that referenced this pull request Nov 11, 2024
…GuillaumeGomez

rustdoc-search: simplify rules for generics and type params

**Heads up!**: This PR is a follow-up that depends on rust-lang#124544. It adds 12dc24f, a change to the filtering behavior, and 9900ea4, a minor ranking tweak.

Part of rust-lang/rust-project-goals#112

This PR overturns rust-lang#109802

## Preview

* no results: [`Box<[A]> -> Vec<B>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CB%3E)
* results: [`Box<[A]> -> Vec<A>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CA%3E)
* [`T -> U`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=T%20-%3E%20U)
* [`Cx -> TyCtxt`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3-compiler/rustdoc/index.html?search=Cx%20-%3E%20TyCtxt)

![image](https://github.com/user-attachments/assets/015ae28c-7469-4f7f-be03-157d28d7ec97)

## Description

This commit is a response to feedback on the displayed type signatures results, by making generics act stricter.

- Order within generics is significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected.
- Generics are only "unboxed" if a type is explicitly opted into it. References and tuples are hardcoded to allow unboxing, and Box, Rc, Arc, Option, Result, and Future are opted in with an unstable attribute. Search result unboxing is the process that allows you to search for `i32 -> str` and get back a function with the type signature `&Future<i32> -> Box<str>`.
- Instead of ranking by set overlap, it ranks by the number of items in the type signature. This makes it easier to find single type signatures like transmute.

## Find the discussion on

* <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149>
* <rust-lang#124544 (comment)>
* <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search>
mati865 pushed a commit to mati865/rust that referenced this pull request Nov 12, 2024
…GuillaumeGomez

rustdoc-search: simplify rules for generics and type params

**Heads up!**: This PR is a follow-up that depends on rust-lang#124544. It adds 12dc24f, a change to the filtering behavior, and 9900ea4, a minor ranking tweak.

Part of rust-lang/rust-project-goals#112

This PR overturns rust-lang#109802

## Preview

* no results: [`Box<[A]> -> Vec<B>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CB%3E)
* results: [`Box<[A]> -> Vec<A>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CA%3E)
* [`T -> U`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=T%20-%3E%20U)
* [`Cx -> TyCtxt`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3-compiler/rustdoc/index.html?search=Cx%20-%3E%20TyCtxt)

![image](https://github.com/user-attachments/assets/015ae28c-7469-4f7f-be03-157d28d7ec97)

## Description

This commit is a response to feedback on the displayed type signatures results, by making generics act stricter.

- Order within generics is significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected.
- Generics are only "unboxed" if a type is explicitly opted into it. References and tuples are hardcoded to allow unboxing, and Box, Rc, Arc, Option, Result, and Future are opted in with an unstable attribute. Search result unboxing is the process that allows you to search for `i32 -> str` and get back a function with the type signature `&Future<i32> -> Box<str>`.
- Instead of ranking by set overlap, it ranks by the number of items in the type signature. This makes it easier to find single type signatures like transmute.

## Find the discussion on

* <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149>
* <rust-lang#124544 (comment)>
* <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search>
github-actions bot pushed a commit to rust-lang/miri that referenced this pull request Nov 15, 2024
…Gomez

rustdoc-search: simplify rules for generics and type params

**Heads up!**: This PR is a follow-up that depends on #124544. It adds 12dc24f46007f82b93ed85614347a42d47580afa, a change to the filtering behavior, and 9900ea48b566656fb12b5fcbd0a1b20aaa96e5ca, a minor ranking tweak.

Part of rust-lang/rust-project-goals#112

This PR overturns rust-lang/rust#109802

## Preview

* no results: [`Box<[A]> -> Vec<B>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CB%3E)
* results: [`Box<[A]> -> Vec<A>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CA%3E)
* [`T -> U`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=T%20-%3E%20U)
* [`Cx -> TyCtxt`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3-compiler/rustdoc/index.html?search=Cx%20-%3E%20TyCtxt)

![image](https://github.com/user-attachments/assets/015ae28c-7469-4f7f-be03-157d28d7ec97)

## Description

This commit is a response to feedback on the displayed type signatures results, by making generics act stricter.

- Order within generics is significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected.
- Generics are only "unboxed" if a type is explicitly opted into it. References and tuples are hardcoded to allow unboxing, and Box, Rc, Arc, Option, Result, and Future are opted in with an unstable attribute. Search result unboxing is the process that allows you to search for `i32 -> str` and get back a function with the type signature `&Future<i32> -> Box<str>`.
- Instead of ranking by set overlap, it ranks by the number of items in the type signature. This makes it easier to find single type signatures like transmute.

## Find the discussion on

* <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149>
* <rust-lang/rust#124544 (comment)>
* <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search>
lnicola pushed a commit to lnicola/rust-analyzer that referenced this pull request Nov 28, 2024
…Gomez

rustdoc-search: simplify rules for generics and type params

**Heads up!**: This PR is a follow-up that depends on #124544. It adds 12dc24f46007f82b93ed85614347a42d47580afa, a change to the filtering behavior, and 9900ea48b566656fb12b5fcbd0a1b20aaa96e5ca, a minor ranking tweak.

Part of rust-lang/rust-project-goals#112

This PR overturns rust-lang/rust#109802

## Preview

* no results: [`Box<[A]> -> Vec<B>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CB%3E)
* results: [`Box<[A]> -> Vec<A>`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=Box%3C%5BA%5D%3E%20-%3E%20Vec%3CA%3E)
* [`T -> U`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3/std/index.html?search=T%20-%3E%20U)
* [`Cx -> TyCtxt`](http://notriddle.com/rustdoc-html-demo-12/search-sem-3-compiler/rustdoc/index.html?search=Cx%20-%3E%20TyCtxt)

![image](https://github.com/user-attachments/assets/015ae28c-7469-4f7f-be03-157d28d7ec97)

## Description

This commit is a response to feedback on the displayed type signatures results, by making generics act stricter.

- Order within generics is significant. This means `Vec<Allocator>` now matches only with a true vector of allocators, instead of matching the second type param. It also makes unboxing within generics stricter, so `Result<A, B>` only matches if `B` is in the error type and `A` is in the success type. The top level of the function search is unaffected.
- Generics are only "unboxed" if a type is explicitly opted into it. References and tuples are hardcoded to allow unboxing, and Box, Rc, Arc, Option, Result, and Future are opted in with an unstable attribute. Search result unboxing is the process that allows you to search for `i32 -> str` and get back a function with the type signature `&Future<i32> -> Box<str>`.
- Instead of ranking by set overlap, it ranks by the number of items in the type signature. This makes it easier to find single type signatures like transmute.

## Find the discussion on

* <https://rust-lang.zulipchat.com/#narrow/stream/393423-t-rustdoc.2Fmeetings/topic/meeting.202024-07-08/near/449965149>
* <rust-lang/rust#124544 (comment)>
* <https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/deciding.20on.20semantics.20of.20generics.20in.20rustdoc.20search>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. finished-final-comment-period The final comment period is finished for this PR / Issue. merged-by-bors This PR was explicitly merged by bors. S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants