rustdoc: sort deprecated items lower in search

[pitaj]

closes #98759

Screenshots

i32::MAX show sup above std::i32::MAX and core::i32::MAX

If just searching for min, the deprecated results show up far below other things:

one page later

And, as you can see, the "Deprecation planned" message shows up in the search results. The same is true for fully-deprecated items like mem::uninitialized:

Edit: the deprecation message change was removed from this PR. Only the sorting is changed.

[rustbot]

r? @jsha

(rustbot has picked a reviewer for you, use r? to override)

[rustbot]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @Folyd, @jsha

[GuillaumeGomez]

Thanks for the PR but no decision was reached on the issue so it might be a bit too early. Don't hesitate to bring it up on the #t-rustdoc channel on our zulip instance.

[tgross35]

no decision was reached on the issue so it might be a bit too early

Fwiw, I think this would still be nice outside of #107587. Probably moreso in crates, which tend to have a lot more deprecations than std, but there are still a few cases floating around there as well.

A deprecated tag in the search results might also be nice similar to #107568, but this might run into the same issues as that. (this might be the case already, I haven't had a chance to build this branch and try it out)

[pitaj]

Okay it seems like this isn't blocked on anything. Should be able to move forward with an FCP here once the review is complete. Zulip discussion for reference

@jsha mind taking a look?

[jsha]

Thanks for working on this! Sorting the deprecated items lower is good; I think we should not add the "Deprecation planned" / "Deprecated" right there in the search results, because it actually draws more attention to the less important items, and because it uses up valuable space.

Implementation-wise, I think the priority where you've placed the sorting-level tweak for deprecation is good. Better string matches should take priority over the deprecation bump. 👍🏻 One thing I notice, looking at these, is that there's a bump for "shorter item name." In theory that should make char::is_ascii rank above std::ascii::AsciiExt::is_ascii even without this PR. But that's not the case. I think there's a separate issue - the "same crate" bump is giving std::ascii::AsciiExt::is_ascii priority when searching in std. We should fix that separately - for instance, by treating all primitives as "same crate" relative to std, core, and alloc.

For storage in the JSON search index, this PR includes a 0 for all non-deprecated items. That's not very efficient for the typical case where most items are non-deprecated. How about instead storing a list of item indexes that are deprecated? And could you include a before/after size of the search index for the std/core/alloc docs (i.e. the output from ./x.py doc)?

[pitaj]

I think we should not add the "Deprecation planned" / "Deprecated" right there in the search results, because it actually draws more attention to the less important items, and because it uses up valuable space.

Hmm. I think having that information in the search results is quite useful and would save people time. What about using a text effect such as strikethrough, color, or opacity?

[pitaj]

@jsha okay I've remove the deprecation message from the search results. I've also switched the deprecated and "full path" columns to a sparse style, reducing the search index size by 4%

search-index.js	size [B]
before	3893476
after	3725618

[pitaj]

One thing I notice, looking at these, is that there's a bump for "shorter item name." In theory that should make char::is_ascii rank above std::ascii::AsciiExt::is_ascii even without this PR. But that's not the case. I think there's a separate issue - the "same crate" bump is giving std::ascii::AsciiExt::is_ascii priority when searching in std. We should fix that separately - for instance, by treating all primitives as "same crate" relative to std, core, and alloc.

I also looked into this a little. It's not that the primitives don't count as being in the preferredCrate, they show up as belonging to std. It's actually that there is no sorting on the item path length, only on the "word" length - which appears to be the portion of the path that matched. We could add a sort on xxx.item.path.length, but it's not clear from my experiment locally whether it consistently produces better results.

[jsha]

Looks great, just one comment fix and we're ready to go.

reducing the search index size by 4%

oh, very nice!

And thanks for the research on why the "shorter name" match wasn't sufficient to rank the primitive associated items higher. That's good to know.

[jsha]

Looks great! Thanks. Want to squash the commits? r=me with that done.

[pitaj]

Squash complete

r? @jsha

[rustbot]

Could not assign reviewer from: jsha.
User(s) jsha are either the PR author or are already assigned, and there are no other candidates.
Use r? to specify someone else to assign.

[notriddle]

@bors r=jsha rollup

[bors]

📌 Commit d2e4b59 has been approved by jsha

It is now in the queue for this repository.

[jsha]

A friend recently pointed out that since this PR, the comment in search.js (which they found very helpful) has gone stale:

rust/src/librustdoc/html/static/js/search.js

Lines 2488 to 2525 in 738df13

	/**
	* The raw search data for a given crate. `n`, `t`, `d`, and `q`, `i`, and `f`
	* are arrays with the same length. n[i] contains the name of an item.
	* t[i] contains the type of that item (as a string of characters that represent an
	* offset in `itemTypes`). d[i] contains the description of that item.
	*
	* q[i] contains the full path of the item, or an empty string indicating
	* "same as q[i-1]".
	*
	* i[i] contains an item's parent, usually a module. For compactness,
	* it is a set of indexes into the `p` array.
	*
	* f[i] contains function signatures, or `0` if the item isn't a function.
	* Functions are themselves encoded as arrays. The first item is a list of
	* types representing the function's inputs, and the second list item is a list
	* of types representing the function's output. Tuples are flattened.
	* Types are also represented as arrays; the first item is an index into the `p`
	* array, while the second is a list of types representing any generic parameters.
	*
	* `a` defines aliases with an Array of pairs: [name, offset], where `offset`
	* points into the n/t/d/q/i/f arrays.
	*
	* `doc` contains the description of the crate.
	*
	* `p` is a list of path/type pairs. It is used for parents and function parameters.
	*
	* @type {{
	* doc: string,
	* a: Object,
	* n: Array<string>,
	* t: String,
	* d: Array<string>,
	* q: Array<[Number, string]>,
	* i: Array<Number>,
	* f: Array<RawFunctionSearchType>,
	* p: Array<Object>,
	* c: Array<Number>
	* }}

@pitaj would you be willing to send another PR fixing the comment to reflect the updated format?

[pitaj]

@jsha sorry about that, comment is fixed in #115490