Skip to content

Autodoc misc enhancements #23751

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.

Sign up for GitHub

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

Open
wants to merge 7 commits into
base: master
Choose a base branch
from
+248 −49
Open

Autodoc misc enhancements #23751

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
18eddf8
Navigating to source from a decl will scroll to the decl
achan1989 Apr 13, 2025
d7cf9be
Fix an out-of-bounds read
achan1989 Apr 19, 2025
b7904af
Fix wrong union field access
achan1989 Apr 19, 2025
1377381
Fix redundant search results
achan1989 Apr 19, 2025
ea4c9c4
up&down arrows keep working when navigating back to search results
achan1989 Apr 19, 2025
7fcd411
Clicking search results preserves the page history
achan1989 Apr 20, 2025
2aff9b3
In source view, make @imports into links
achan1989 Apr 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 90 additions & 21 deletions lib/docs/main.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,9 @@
const domErrors = document.getElementById("errors");
const domErrorsText = document.getElementById("errorsText");

// Chosen to prevent collisions with the IDs above.
const navPrefix = "nav_";

var searchTimer = null;

const curNav = {
Expand All @@ -67,14 +70,18 @@
decl: null,
// string file name matching tarball path
path: null,
// string decl path within source file
scrollToDeclPath: null,

// when this is populated, pressing the "view source" command will
// navigate to this hash.
viewSourceHash: null,
};
var curNavSearch = "";
var curSearchIndex = -1;
var imFeelingLucky = false;
// When true: load the search result indicated by `curSearchIndex`, or the first result if
// `curSearchIndex` isn't valid.
var loadSearchResult = false;

// names of modules in the same order as wasm
const moduleList = [];
Expand Down Expand Up @@ -180,7 +187,7 @@
} else {
return renderDecl(curNav.decl);
}
case 2: return renderSource(curNav.path);
case 2: return renderSource(curNav.path, curNav.scrollToDeclPath);
default: throw new Error("invalid navigation state");
}
}
Expand Down Expand Up @@ -224,22 +231,43 @@
}
}

function renderSource(path) {
const decl_index = findFileRoot(path);
if (decl_index == null) return renderNotFound();
function renderSource(path, scroll_to_decl_path) {
const root_index = findFileRoot(path);
if (root_index == null) return renderNotFound();

renderNavFancy(decl_index, [{
renderNavFancy(root_index, [{
name: "[src]",
href: location.hash,
}]);

domSourceText.innerHTML = declSourceHtml(decl_index);

domSourceText.innerHTML = declSourceHtml(root_index, true);
domSectSource.classList.remove("hidden");

const scroll_to_decl_index = findDeclPathInNamespace(root_index, scroll_to_decl_path);
if (scroll_to_decl_index !== null) {
const to_elem = document.getElementById(navPrefix + scroll_to_decl_index);
if (to_elem != null) {
// Needs a delay, else the DOM hasn't been fully updated and the scroll does nothing.
setTimeout(function() {to_elem.scrollIntoView();}, 0);
}
}
}

function renderDeclHeading(decl_index) {
curNav.viewSourceHash = "#src/" + unwrapString(wasm_exports.decl_file_path(decl_index));
const is_root = wasm_exports.decl_is_root(decl_index);
if (!is_root) {
// E.g. if `decl_index` corresponds to `root.foo.bar` we want `foo.bar`
var subcomponents = [];
let decl_it = decl_index;
while (decl_it != null) {
subcomponents.push(declIndexName(decl_it));
decl_it = declParent(decl_it);
}
subcomponents.pop();
subcomponents.reverse();
curNav.viewSourceHash += ":" + subcomponents.join(".");
}

const hdrNameSpan = domHdrName.children[0];
const srcLink = domHdrName.children[1];
Expand Down Expand Up @@ -384,7 +412,7 @@
if (members.length !== 0 || fields.length !== 0) {
renderNamespace(decl_index, members, fields);
} else {
domSourceText.innerHTML = declSourceHtml(decl_index);
domSourceText.innerHTML = declSourceHtml(decl_index, false);
domSectSource.classList.remove("hidden");
}
}
Expand Down Expand Up @@ -414,7 +442,7 @@
renderErrorSet(base_decl, errorSetNodeList(decl_index, errorSetNode));
}

domSourceText.innerHTML = declSourceHtml(decl_index);
domSourceText.innerHTML = declSourceHtml(decl_index, false);
domSectSource.classList.remove("hidden");
}

Expand All @@ -428,7 +456,7 @@
domTldDocs.classList.remove("hidden");
}

domSourceText.innerHTML = declSourceHtml(decl_index);
domSourceText.innerHTML = declSourceHtml(decl_index, false);
domSectSource.classList.remove("hidden");
}

Expand Down Expand Up @@ -615,6 +643,7 @@
curNav.tag = 0;
curNav.decl = null;
curNav.path = null;
curNav.scrollToDeclPath = null;
curNav.viewSourceHash = null;
curNavSearch = "";

Expand All @@ -633,7 +662,13 @@
const source_mode = nonSearchPart.startsWith("src/");
if (source_mode) {
curNav.tag = 2;
curNav.path = nonSearchPart.substring(4);
const idpos = nonSearchPart.indexOf(":");
if (idpos === -1) {
curNav.path = nonSearchPart.substring(4);
} else {
curNav.path = nonSearchPart.substring(4, idpos);
curNav.scrollToDeclPath = nonSearchPart.substring(idpos + 1);
}
} else {
curNav.tag = 1;
curNav.decl = findDecl(nonSearchPart);
Expand All @@ -643,9 +678,14 @@
}

function onHashChange(state) {
if (state != null) {
const restore_search_index = state.curSearchIndex;
if (restore_search_index !== undefined) curSearchIndex = restore_search_index;
}
history.replaceState({}, "");
navigate(location.hash);
if (state == null) window.scrollTo({top: 0});
if (curNavSearch !== "") domSearch.focus({preventScroll: true});
}

function onPopState(ev) {
Expand All @@ -658,12 +698,25 @@
domSearch.value = curNavSearch;
}
render();
if (imFeelingLucky) {
imFeelingLucky = false;
if (loadSearchResult) {
loadSearchResult = false;
activateSelectedResult();
}
}

function doLoadSearchResult() {
clearAsyncSearch();
loadSearchResult = true;
const old_hash = location.hash;
location.hash = computeSearchHash();
if (location.hash === old_hash) {
// With certain sequences of history navigation and input, setting location.hash here
// causes no change, and the enter key isn't acted on until another modification is made
// to the search text. Force navigation to work around this.
navigate(location.hash);
}
}

function activateSelectedResult() {
if (domSectSearchResults.classList.contains("hidden")) {
return;
Expand All @@ -675,21 +728,29 @@
}
if (liDom != null) {
var aDom = liDom.children[0];
history.replaceState({curSearchIndex: curSearchIndex}, "");
location.href = aDom.getAttribute("href");
curSearchIndex = -1;
}
domSearch.blur();
}

function onSearchResultClick(ev) {
const liDom = ev.target.parentElement;
const search_index = Array.from(domListSearchResults.children).indexOf(liDom);
curSearchIndex = search_index;
doLoadSearchResult();

ev.preventDefault();
ev.stopPropagation();
}

function onSearchKeyDown(ev) {
switch (ev.code) {
case "Enter":
if (ev.shiftKey || ev.ctrlKey || ev.altKey) return;

clearAsyncSearch();
imFeelingLucky = true;
location.hash = computeSearchHash();

doLoadSearchResult();
ev.preventDefault();
ev.stopPropagation();
return;
Expand Down Expand Up @@ -836,6 +897,7 @@
const full_name = fullyQualifiedName(match);
aDom.textContent = full_name;
aDom.setAttribute('href', navLinkFqn(full_name));
aDom.addEventListener("click", onSearchResultClick);
}
renderSearchCursor();

Expand Down Expand Up @@ -904,8 +966,8 @@
return unwrapString(wasm_exports.decl_name(decl_index));
}

function declSourceHtml(decl_index) {
return unwrapString(wasm_exports.decl_source_html(decl_index));
function declSourceHtml(decl_index, decl_nav_targets) {
return unwrapString(wasm_exports.decl_source_html(decl_index, decl_nav_targets));
}

function declDoctestHtml(decl_index) {
Expand Down Expand Up @@ -973,6 +1035,13 @@
return result;
}

function findDeclPathInNamespace(namespace_decl_index, path) {
setInputString(path);
const result = wasm_exports.find_decl_path_in_namespace(namespace_decl_index);
if (result === -1) return null;
return result;
}

function findFileRoot(path) {
setInputString(path);
const result = wasm_exports.find_file_root();
Expand All @@ -988,7 +1057,7 @@

function fnErrorSet(decl_index) {
const result = wasm_exports.fn_error_set(decl_index);
if (result === 0) return null;
if (result === 0 || result === -1) return null;
return result;
}

Expand Down
2 changes: 1 addition & 1 deletion lib/docs/wasm/Decl.zig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ pub fn get_type_fn_return_expr(decl: *const Decl) ?Ast.Node.Index {

for (statements) |stmt| {
if (ast.nodeTag(stmt) == .@"return") {
return ast.nodeData(stmt).node;
if (ast.nodeData(stmt).opt_node.unwrap()) |expr_node| return expr_node;
}
}
return null;
Expand Down
Loading