From 28f17d97a9e7276a383e11e91ef2d4159e670726 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Mon, 20 Nov 2023 13:37:57 -0700 Subject: [PATCH] rustdoc-search: make primitives and keywords less special The search sorting code already sorts by item type discriminant, putting things with smaller discriminants first. There was also a special case for sorting keywords and primitives earlier, and this commit removes it by giving them lower discriminants. The sorting code has another criteria where items with descriptions appear earlier than items without, and that criteria has higher priority than the item type. This shouldn't matter, though, because primitives and keywords normally only appear in the standard library, and it always gives them descriptions. --- src/librustdoc/formats/item_type.rs | 51 ++++++++++++---------- src/librustdoc/html/static/js/search.js | 36 +++++---------- tests/rustdoc-js-std/keyword.js | 4 +- tests/rustdoc-js-std/macro-check.js | 4 +- tests/rustdoc-js-std/parser-bindings.js | 8 ++-- tests/rustdoc-js-std/parser-filter.js | 22 +++++----- tests/rustdoc-js-std/parser-ident.js | 6 +-- tests/rustdoc-js-std/parser-returned.js | 2 +- tests/rustdoc-js-std/parser-slice-array.js | 20 ++++----- 9 files changed, 74 insertions(+), 79 deletions(-) diff --git a/src/librustdoc/formats/item_type.rs b/src/librustdoc/formats/item_type.rs index 22527876b76..5666751d1ce 100644 --- a/src/librustdoc/formats/item_type.rs +++ b/src/librustdoc/formats/item_type.rs @@ -16,6 +16,13 @@ /// Consequently, every change to this type should be synchronized to /// the `itemTypes` mapping table in `html/static/js/search.js`. /// +/// The search engine in search.js also uses item type numbers as a tie breaker when +/// sorting results. Keywords and primitives are given first because we want them to be easily +/// found by new users who don't know about advanced features like type filters. The rest are +/// mostly in an arbitrary order, but it's easier to test the search engine when +/// it's deterministic, and these are strictly finer-grained than language namespaces, so +/// using the path and the item type together to sort ensures that search sorting is stable. +/// /// In addition, code in `html::render` uses this enum to generate CSS classes, page prefixes, and /// module headings. If you are adding to this enum and want to ensure that the sidebar also prints /// a heading, edit the listing in `html/render.rs`, function `sidebar_module`. This uses an @@ -23,28 +30,28 @@ #[derive(Copy, PartialEq, Eq, Hash, Clone, Debug, PartialOrd, Ord)] #[repr(u8)] pub(crate) enum ItemType { - Module = 0, - ExternCrate = 1, - Import = 2, - Struct = 3, - Enum = 4, - Function = 5, - TypeAlias = 6, - Static = 7, - Trait = 8, - Impl = 9, - TyMethod = 10, - Method = 11, - StructField = 12, - Variant = 13, - Macro = 14, - Primitive = 15, - AssocType = 16, - Constant = 17, - AssocConst = 18, - Union = 19, - ForeignType = 20, - Keyword = 21, + Keyword = 0, + Primitive = 1, + Module = 2, + ExternCrate = 3, + Import = 4, + Struct = 5, + Enum = 6, + Function = 7, + TypeAlias = 8, + Static = 9, + Trait = 10, + Impl = 11, + TyMethod = 12, + Method = 13, + StructField = 14, + Variant = 15, + Macro = 16, + AssocType = 17, + Constant = 18, + AssocConst = 19, + Union = 20, + ForeignType = 21, OpaqueTy = 22, ProcAttribute = 23, ProcDerive = 24, diff --git a/src/librustdoc/html/static/js/search.js b/src/librustdoc/html/static/js/search.js index 495c28d91e8..4822690fd04 100644 --- a/src/librustdoc/html/static/js/search.js +++ b/src/librustdoc/html/static/js/search.js @@ -18,28 +18,28 @@ if (!Array.prototype.toSpliced) { // This mapping table should match the discriminants of // `rustdoc::formats::item_type::ItemType` type in Rust. const itemTypes = [ + "keyword", + "primitive", "mod", "externcrate", "import", - "struct", + "struct", // 5 "enum", - "fn", // 5 + "fn", "type", "static", - "trait", + "trait", // 10 "impl", - "tymethod", // 10 + "tymethod", "method", "structfield", - "variant", + "variant", // 15 "macro", - "primitive", // 15 "associatedtype", "constant", "associatedconstant", - "union", - "foreigntype", // 20 - "keyword", + "union", // 20 + "foreigntype", "existential", "attr", "derive", @@ -48,6 +48,8 @@ const itemTypes = [ ]; const longItemTypes = [ + "keyword", + "primitive type", "module", "extern crate", "re-export", @@ -63,13 +65,11 @@ const longItemTypes = [ "struct field", "enum variant", "macro", - "primitive type", "assoc type", "constant", "assoc const", "union", "foreign type", - "keyword", "existential type", "attribute macro", "derive macro", @@ -77,8 +77,6 @@ const longItemTypes = [ ]; // used for special search precedence -const TY_PRIMITIVE = itemTypes.indexOf("primitive"); -const TY_KEYWORD = itemTypes.indexOf("keyword"); const TY_GENERIC = itemTypes.indexOf("generic"); const ROOT_PATH = typeof window !== "undefined" ? window.rootPath : "../"; @@ -1317,16 +1315,6 @@ function initSearch(rawSearchIndex) { return (a > b ? +1 : -1); } - // special precedence for primitive and keyword pages - if ((aaa.item.ty === TY_PRIMITIVE && bbb.item.ty !== TY_KEYWORD) || - (aaa.item.ty === TY_KEYWORD && bbb.item.ty !== TY_PRIMITIVE)) { - return -1; - } - if ((bbb.item.ty === TY_PRIMITIVE && aaa.item.ty !== TY_PRIMITIVE) || - (bbb.item.ty === TY_KEYWORD && aaa.item.ty !== TY_KEYWORD)) { - return 1; - } - // sort by description (no description goes later) a = (aaa.item.desc === ""); b = (bbb.item.desc === ""); @@ -2943,7 +2931,7 @@ ${item.displayPath}${name}\ // https://mathiasbynens.be/notes/shapes-ics const crateRow = { crate: crate, - ty: 1, // == ExternCrate + ty: 3, // == ExternCrate name: crate, path: "", desc: crateCorpus.doc, diff --git a/tests/rustdoc-js-std/keyword.js b/tests/rustdoc-js-std/keyword.js index b85ba34138b..1837b1e71f7 100644 --- a/tests/rustdoc-js-std/keyword.js +++ b/tests/rustdoc-js-std/keyword.js @@ -3,7 +3,7 @@ const EXPECTED = { 'query': 'fn', 'others': [ - { 'path': 'std', 'name': 'fn', ty: 15 }, // 15 is for primitive types - { 'path': 'std', 'name': 'fn', ty: 21 }, // 21 is for keywords + { 'path': 'std', 'name': 'fn', ty: 1 }, // 1 is for primitive types + { 'path': 'std', 'name': 'fn', ty: 0 }, // 0 is for keywords ], }; diff --git a/tests/rustdoc-js-std/macro-check.js b/tests/rustdoc-js-std/macro-check.js index c22b1753fd7..37d5e7dae62 100644 --- a/tests/rustdoc-js-std/macro-check.js +++ b/tests/rustdoc-js-std/macro-check.js @@ -3,7 +3,7 @@ const EXPECTED = { 'query': 'panic', 'others': [ - { 'path': 'std', 'name': 'panic', ty: 14 }, // 15 is for macros - { 'path': 'std', 'name': 'panic', ty: 0 }, // 0 is for modules + { 'path': 'std', 'name': 'panic', ty: 16 }, // 16 is for macros + { 'path': 'std', 'name': 'panic', ty: 2 }, // 2 is for modules ], }; diff --git a/tests/rustdoc-js-std/parser-bindings.js b/tests/rustdoc-js-std/parser-bindings.js index faf880c8116..c4909c6242d 100644 --- a/tests/rustdoc-js-std/parser-bindings.js +++ b/tests/rustdoc-js-std/parser-bindings.js @@ -81,7 +81,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "never", generics: [], - typeFilter: 15, + typeFilter: 1, }] ], ], @@ -112,7 +112,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "[]", generics: [], - typeFilter: 15, + typeFilter: 1, }] ], ], @@ -149,10 +149,10 @@ const PARSED = [ pathWithoutLast: [], pathLast: "never", generics: [], - typeFilter: 15, + typeFilter: 1, }, ], - typeFilter: 15, + typeFilter: 1, }] ], ], diff --git a/tests/rustdoc-js-std/parser-filter.js b/tests/rustdoc-js-std/parser-filter.js index 3b9cc5b1bf0..a1dd0ea3b5a 100644 --- a/tests/rustdoc-js-std/parser-filter.js +++ b/tests/rustdoc-js-std/parser-filter.js @@ -7,7 +7,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "foo", generics: [], - typeFilter: 5, + typeFilter: 7, }], foundElems: 1, original: "fn:foo", @@ -23,7 +23,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "foo", generics: [], - typeFilter: 4, + typeFilter: 6, }], foundElems: 1, original: "enum : foo", @@ -48,7 +48,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "macro", generics: [], - typeFilter: 14, + typeFilter: 16, }], foundElems: 1, original: "macro!", @@ -64,7 +64,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "mac", generics: [], - typeFilter: 14, + typeFilter: 16, }], foundElems: 1, original: "macro:mac!", @@ -80,7 +80,7 @@ const PARSED = [ pathWithoutLast: ["a"], pathLast: "mac", generics: [], - typeFilter: 14, + typeFilter: 16, }], foundElems: 1, original: "a::mac!", @@ -99,7 +99,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "foo", generics: [], - typeFilter: 5, + typeFilter: 7, }], userQuery: "-> fn:foo", error: null, @@ -121,10 +121,10 @@ const PARSED = [ pathWithoutLast: [], pathLast: "bar", generics: [], - typeFilter: 5, + typeFilter: 7, } ], - typeFilter: 5, + typeFilter: 7, }], userQuery: "-> fn:foo", error: null, @@ -146,7 +146,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "bar", generics: [], - typeFilter: 5, + typeFilter: 7, }, { name: "baz::fuzz", @@ -154,10 +154,10 @@ const PARSED = [ pathWithoutLast: ["baz"], pathLast: "fuzz", generics: [], - typeFilter: 4, + typeFilter: 6, }, ], - typeFilter: 5, + typeFilter: 7, }], userQuery: "-> fn:foo", error: null, diff --git a/tests/rustdoc-js-std/parser-ident.js b/tests/rustdoc-js-std/parser-ident.js index f65a7ce6692..cc79c58f1da 100644 --- a/tests/rustdoc-js-std/parser-ident.js +++ b/tests/rustdoc-js-std/parser-ident.js @@ -13,7 +13,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "never", generics: [], - typeFilter: 15, + typeFilter: 1, }, ], typeFilter: -1, @@ -32,7 +32,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "never", generics: [], - typeFilter: 15, + typeFilter: 1, }], foundElems: 1, original: "!", @@ -48,7 +48,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "a", generics: [], - typeFilter: 14, + typeFilter: 16, }], foundElems: 1, original: "a!", diff --git a/tests/rustdoc-js-std/parser-returned.js b/tests/rustdoc-js-std/parser-returned.js index 6ea86609115..44e517c49b5 100644 --- a/tests/rustdoc-js-std/parser-returned.js +++ b/tests/rustdoc-js-std/parser-returned.js @@ -89,7 +89,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "never", generics: [], - typeFilter: 15, + typeFilter: 1, }], userQuery: "-> !", error: null, diff --git a/tests/rustdoc-js-std/parser-slice-array.js b/tests/rustdoc-js-std/parser-slice-array.js index c22b7870dbf..239391bed42 100644 --- a/tests/rustdoc-js-std/parser-slice-array.js +++ b/tests/rustdoc-js-std/parser-slice-array.js @@ -43,16 +43,16 @@ const PARSED = [ pathWithoutLast: [], pathLast: "[]", generics: [], - typeFilter: 15, + typeFilter: 1, }, ], - typeFilter: 15, + typeFilter: 1, }, ], - typeFilter: 15, + typeFilter: 1, }, ], - typeFilter: 15, + typeFilter: 1, }, ], foundElems: 1, @@ -70,7 +70,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "[]", generics: [], - typeFilter: 15, + typeFilter: 1, }, { name: "u8", @@ -105,7 +105,7 @@ const PARSED = [ typeFilter: -1, }, ], - typeFilter: 15, + typeFilter: 1, }, ], foundElems: 1, @@ -140,7 +140,7 @@ const PARSED = [ typeFilter: -1, }, ], - typeFilter: 15, + typeFilter: 1, }, ], foundElems: 1, @@ -176,7 +176,7 @@ const PARSED = [ typeFilter: -1, }, ], - typeFilter: 15, + typeFilter: 1, }, ], foundElems: 1, @@ -194,7 +194,7 @@ const PARSED = [ pathWithoutLast: [], pathLast: "[]", generics: [], - typeFilter: 15, + typeFilter: 1, }, ], foundElems: 1, @@ -284,7 +284,7 @@ const PARSED = [ typeFilter: -1, }, ], - typeFilter: 15, + typeFilter: 1, }, ], foundElems: 1,