user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rollup merge of #71724 - GuillaumeGomez:doc-alias-improvements, r=ollie27

Browse source 
Doc alias improvements

After [this message](https://github.com/rust-lang/rust/issues/50146#issuecomment-496601755), 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
This commit is contained in:
Dylan DPC 2020-05-16 02:37:19 +02:00 • committed by GitHub
commit 154db50d86
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 562 additions and 144 deletions
Download patch file Download diff file Expand all files Collapse all files

1
src/librustdoc/html/layout.rs
View file

@ -114,7 +114,6 @@ pub fn render<T: Print, S: Print>(
window.rootPath = \"{root_path}\";\
window.currentCrate = \"{krate}\";\
</script>\
<script src=\"{root_path}aliases{suffix}.js\"></script>\
<script src=\"{static_root_path}main{suffix}.js\"></script>\
{static_extra_scripts}\
{extra_scripts}\

43
src/librustdoc/html/render.rs
View file

@ -293,7 +293,12 @@ impl Serialize for IndexItem {
where
S: Serializer,
{
assert_eq!(self.parent.is_some(), self.parent_idx.is_some());
assert_eq!(
self.parent.is_some(),
self.parent_idx.is_some(),
"`{}` is missing idx",
self.name
);
(self.ty, &self.name, &self.path, &self.desc, self.parent_idx, &self.search_type)
.serialize(serializer)
@ -819,42 +824,6 @@ themePicker.onblur = handleThemeButtonsBlur;
Ok((ret, krates))
}
fn show_item(item: &IndexItem, krate: &str) -> String {
format!(
"{{'crate':'{}','ty':{},'name':'{}','desc':'{}','p':'{}'{}}}",
krate,
item.ty as usize,
item.name,
item.desc.replace("'", "\\'"),
item.path,
if let Some(p) = item.parent_idx { format!(",'parent':{}", p) } else { String::new() }
)
}
let dst = cx.dst.join(&format!("aliases{}.js", cx.shared.resource_suffix));
{
let (mut all_aliases, _) = try_err!(collect(&dst, &krate.name, "ALIASES"), &dst);
let mut output = String::with_capacity(100);
for (alias, items) in &cx.cache.aliases {
if items.is_empty() {
continue;
}
output.push_str(&format!(
"\"{}\":[{}],",
alias,
items.iter().map(|v| show_item(v, &krate.name)).collect::<Vec<_>>().join(",")
));
}
all_aliases.push(format!("ALIASES[\"{}\"] = {{{}}};", krate.name, output));
all_aliases.sort();
let mut v = Buffer::html();
writeln!(&mut v, "var ALIASES = {{}};");
for aliases in &all_aliases {
writeln!(&mut v, "{}", aliases);
}
cx.shared.fs.write(&dst, v.into_inner().into_bytes())?;
}
use std::ffi::OsString;
#[derive(Debug)]

64
src/librustdoc/html/render/cache.rs
View file

@ -120,7 +120,7 @@ crate struct Cache {
/// Aliases added through `#[doc(alias = "...")]`. Since a few items can have the same alias,
/// we need the alias element to have an array of items.
pub(super) aliases: FxHashMap<String, Vec<IndexItem>>,
pub(super) aliases: BTreeMap<String, Vec<usize>>,
}
impl Cache {
@ -311,7 +311,7 @@ impl DocFolder for Cache {
};
match parent {
(parent, Some(path)) if is_inherent_impl_item || (!self.stripped_mod) => {
(parent, Some(path)) if is_inherent_impl_item || !self.stripped_mod => {
debug_assert!(!item.is_stripped());
// A crate has a module at its root, containing all items,
@ -327,6 +327,13 @@ impl DocFolder for Cache {
parent_idx: None,
search_type: get_index_search_type(&item),
});
for alias in item.attrs.get_doc_aliases() {
self.aliases
.entry(alias.to_lowercase())
.or_insert(Vec::new())
.push(self.search_index.len() - 1);
}
}
}
(Some(parent), None) if is_inherent_impl_item => {
@ -376,11 +383,8 @@ impl DocFolder for Cache {
{
self.paths.insert(item.def_id, (self.stack.clone(), item.type_()));
}
self.add_aliases(&item);
}
clean::PrimitiveItem(..) => {
self.add_aliases(&item);
self.paths.insert(item.def_id, (self.stack.clone(), item.type_()));
}
@ -488,40 +492,6 @@ impl DocFolder for Cache {
}
}
impl Cache {
fn add_aliases(&mut self, item: &clean::Item) {
if item.def_id.index == CRATE_DEF_INDEX {
return;
}
if let Some(ref item_name) = item.name {
let path = self
.paths
.get(&item.def_id)
.map(|p| p.0[..p.0.len() - 1].join("::"))
.unwrap_or("std".to_owned());
for alias in item
.attrs
.lists(sym::doc)
.filter(|a| a.check_name(sym::alias))
.filter_map(|a| a.value_str().map(|s| s.to_string().replace("\"", "")))
.filter(|v| !v.is_empty())
.collect::<FxHashSet<_>>()
.into_iter()
{
self.aliases.entry(alias).or_insert(Vec::with_capacity(1)).push(IndexItem {
ty: item.type_(),
name: item_name.to_string(),
path: path.clone(),
desc: shorten(plain_summary_line(item.doc_value())),
parent: None,
parent_idx: None,
search_type: get_index_search_type(&item),
});
}
}
}
}
/// Attempts to find where an external crate is located, given that we're
/// rendering in to the specified source destination.
fn extern_location(
@ -567,7 +537,8 @@ fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String {
let mut crate_items = Vec::with_capacity(cache.search_index.len());
let mut crate_paths = vec![];
let Cache { ref mut search_index, ref orphan_impl_items, ref paths, .. } = *cache;
let Cache { ref mut search_index, ref orphan_impl_items, ref paths, ref mut aliases, .. } =
*cache;
// Attach all orphan items to the type's definition if the type
// has since been learned.
@ -582,6 +553,12 @@ fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String {
parent_idx: None,
search_type: get_index_search_type(&item),
});
for alias in item.attrs.get_doc_aliases() {
aliases
.entry(alias.to_lowercase())
.or_insert(Vec::new())
.push(search_index.len() - 1);
}
}
}
@ -630,6 +607,12 @@ fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String {
items: Vec<&'a IndexItem>,
#[serde(rename = "p")]
paths: Vec<(ItemType, String)>,
// The String is alias name and the vec is the list of the elements with this alias.
//
// To be noted: the `usize` elements are indexes to `items`.
#[serde(rename = "a")]
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
aliases: &'a BTreeMap<String, Vec<usize>>,
}
// Collect the index into a string
@ -640,6 +623,7 @@ fn build_index(krate: &clean::Crate, cache: &mut Cache) -> String {
doc: crate_doc,
items: crate_items,
paths: crate_paths,
aliases,
})
.expect("failed serde conversion")
// All these `replace` calls are because we have to go through JS string for JSON content.

136
src/librustdoc/html/static/main.js
View file

@ -531,6 +531,7 @@ function getSearchElement() {
var OUTPUT_DATA = 1;
var NO_TYPE_FILTER = -1;
var currentResults, index, searchIndex;
var ALIASES = {};
var params = getQueryStringParams();
// Populate search bar with query string search term when provided,
@ -963,6 +964,72 @@ function getSearchElement() {
return itemTypes[ty.ty] + ty.path + ty.name;
}
function createAliasFromItem(item) {
return {
crate: item.crate,
name: item.name,
path: item.path,
desc: item.desc,
ty: item.ty,
parent: item.parent,
type: item.type,
is_alias: true,
};
}
function handleAliases(ret, query, filterCrates) {
// We separate aliases and crate aliases because we want to have current crate
// aliases to be before the others in the displayed results.
var aliases = [];
var crateAliases = [];
var i;
if (filterCrates !== undefined &&
ALIASES[filterCrates] &&
ALIASES[filterCrates][query.search]) {
for (i = 0; i < ALIASES[crate][query.search].length; ++i) {
aliases.push(
createAliasFromItem(searchIndex[ALIASES[filterCrates][query.search]]));
}
} else {
Object.keys(ALIASES).forEach(function(crate) {
if (ALIASES[crate][query.search]) {
var pushTo = crate === window.currentCrate ? crateAliases : aliases;
for (i = 0; i < ALIASES[crate][query.search].length; ++i) {
pushTo.push(
createAliasFromItem(
searchIndex[ALIASES[crate][query.search][i]]));
}
}
});
}
var sortFunc = function(aaa, bbb) {
if (aaa.path < bbb.path) {
return 1;
} else if (aaa.path === bbb.path) {
return 0;
}
return -1;
};
crateAliases.sort(sortFunc);
aliases.sort(sortFunc);
var pushFunc = function(alias) {
alias.alias = query.raw;
var res = buildHrefAndPath(alias);
alias.displayPath = pathSplitter(res[0]);
alias.fullPath = alias.displayPath + alias.name;
alias.href = res[1];
ret.others.unshift(alias);
if (ret.others.length > MAX_RESULTS) {
ret.others.pop();
}
};
onEach(aliases, pushFunc);
onEach(crateAliases, pushFunc);
}
// quoted values mean literal search
var nSearchWords = searchWords.length;
var i;
@ -1190,23 +1257,7 @@ function getSearchElement() {
"returned": sortResults(results_returned, true),
"others": sortResults(results),
};
if (ALIASES && ALIASES[window.currentCrate] &&
ALIASES[window.currentCrate][query.raw]) {
var aliases = ALIASES[window.currentCrate][query.raw];
for (i = 0; i < aliases.length; ++i) {
aliases[i].is_alias = true;
aliases[i].alias = query.raw;
aliases[i].path = aliases[i].p;
var res = buildHrefAndPath(aliases[i]);
aliases[i].displayPath = pathSplitter(res[0]);
aliases[i].fullPath = aliases[i].displayPath + aliases[i].name;
aliases[i].href = res[1];
ret.others.unshift(aliases[i]);
if (ret.others.length > MAX_RESULTS) {
ret.others.pop();
}
}
}
handleAliases(ret, query, filterCrates);
return ret;
}
@ -1599,13 +1650,12 @@ function getSearchElement() {
"returned": mergeArrays(results.returned),
"others": mergeArrays(results.others),
};
} else {
return {
"in_args": results.in_args[0],
"returned": results.returned[0],
"others": results.others[0],
};
}
return {
"in_args": results.in_args[0],
"returned": results.returned[0],
"others": results.others[0],
};
}
function getFilterCrates() {
@ -1656,10 +1706,13 @@ function getSearchElement() {
searchIndex = [];
var searchWords = [];
var i;
var currentIndex = 0;
for (var crate in rawSearchIndex) {
if (!rawSearchIndex.hasOwnProperty(crate)) { continue; }
var crateSize = 0;
searchWords.push(crate);
searchIndex.push({
crate: crate,
@ -1669,6 +1722,7 @@ function getSearchElement() {
desc: rawSearchIndex[crate].doc,
type: null,
});
currentIndex += 1;
// an array of [(Number) item type,
// (String) name,
@ -1680,6 +1734,9 @@ function getSearchElement() {
// an array of [(Number) item type,
// (String) name]
var paths = rawSearchIndex[crate].p;
// a array of [(String) alias name
// [Number] index to items]
var aliases = rawSearchIndex[crate].a;
// convert `rawPaths` entries into object form
var len = paths.length;
@ -1698,9 +1755,18 @@ function getSearchElement() {
var lastPath = "";
for (i = 0; i < len; ++i) {
var rawRow = items[i];
var row = {crate: crate, ty: rawRow[0], name: rawRow[1],
path: rawRow[2] || lastPath, desc: rawRow[3],
parent: paths[rawRow[4]], type: rawRow[5]};
if (!rawRow[2]) {
rawRow[2] = lastPath;
}
var row = {
crate: crate,
ty: rawRow[0],
name: rawRow[1],
path: rawRow[2],
desc: rawRow[3],
parent: paths[rawRow[4]],
type: rawRow[5],
};
searchIndex.push(row);
if (typeof row.name === "string") {
var word = row.name.toLowerCase();
@ -1709,7 +1775,25 @@ function getSearchElement() {
searchWords.push("");
}
lastPath = row.path;
crateSize += 1;
}
if (aliases) {
ALIASES[crate] = {};
var j, local_aliases;
for (var alias_name in aliases) {
if (!aliases.hasOwnProperty(alias_name)) { continue; }
if (!ALIASES[crate].hasOwnProperty(alias_name)) {
ALIASES[crate][alias_name] = [];
}
local_aliases = aliases[alias_name];
for (j = 0; j < local_aliases.length; ++j) {
ALIASES[crate][alias_name].push(local_aliases[j] + currentIndex);
}
}
}
currentIndex += crateSize;
}
return searchWords;
}