motiejus/zig
1
Fork 0
Code Releases Activity

autodoc: show more doc comments for namespaces and types

Browse Source 
previously, in the container view (the type of view that you see when
you look at `std` for example), when listing types and namespaces, we
would only show doc comments places on the direct child decl, which in
the case of the `std` namespace, for example, it's just a bunch of
re-exports.

now, if we don't find a direct doc comment, we chase indirection and
display doc comments placed directly on the definition, if any.

this is the precise priority order:

```
/// 1
pub const Foo = _Foo;

/// 2
const _Foo = struct {
   //! 3
};
```
The numbers show the priority order for autodoc.
This commit is contained in:
Loris Cro
2023-09-20 19:17:00 +02:00
parent a63a1c5cb9
commit c481510c99
1 changed files with 44 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
lib/docs/main.js
View File

@@ -3053,8 +3053,21 @@ Happy writing!
if (typeIsErrSet(declValue.expr.type)) {
errSetsList.push(decl);
} else if (typeIsStructWithNoFields(declValue.expr.type)) {
if (getAstNode(decl.src).docs) {
namespacesWithDocsList.push(decl);
let docs = getAstNode(decl.src).docs;
if (!docs) {
// If this is a re-export, try to fetch docs from the actual definition
const { value, seenDecls } = resolveValue(decl.value, true);
if (seenDecls.length > 0) {
const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
docs = getAstNode(definitionDecl.src).docs;
} else {
docs = getAstNode(getType(value.expr.type).src).docs;
}
}
if (docs) {
namespacesWithDocsList.push({decl, docs});
} else {
namespacesNoDocsList.push(decl);
}
@@ -3068,8 +3081,19 @@ Happy writing!
if (typeIsErrSet(declValue.expr.type)) {
errSetsList.push(decl);
} else if (typeIsStructWithNoFields(declValue.expr.type)) {
if (getAstNode(decl.src).docs) {
namespacesWithDocsList.push(decl);
let docs = getAstNode(decl.src).docs;
if (!docs) {
// If this is a re-export, try to fetch docs from the actual definition
const { value, seenDecls } = resolveValue(decl.value, true);
if (seenDecls.length > 0) {
const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
docs = getAstNode(definitionDecl.src).docs;
} else {
docs = getAstNode(getType(value.expr.type).src).docs;
}
}
if (docs) {
namespacesWithDocsList.push({decl, docs});
} else {
namespacesNoDocsList.push(decl);
}
@@ -3215,8 +3239,19 @@ Happy writing!
let descDom = liDom.children[1];
let docs = getAstNode(decl.src).docs;
if (!docs) {
// If this is a re-export, try to fetch docs from the actual definition
const { value, seenDecls } = resolveValue(decl.value, true);
if (seenDecls.length > 0) {
const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
docs = getAstNode(definitionDecl.src).docs;
} else {
docs = getAstNode(getType(value.expr.type).src).docs;
}
}
if (docs) {
descDom.innerHTML = markdown(shortDesc(getAstNode(decl.src).docs));
descDom.innerHTML = markdown(shortDesc(docs));
} else {
descDom.innerHTML = "<p class='understated'><i>No documentation provided.</i></p>";
}
@@ -3241,16 +3276,17 @@ Happy writing!
for (let i = 0; i < namespacesWithDocsList.length; i += 1) {
let liDom = activeList.children[i - offset];
let aDom = liDom.children[0];
let decl = namespacesWithDocsList[i];
let { decl, docs } = namespacesWithDocsList[i];
aDom.textContent = decl.name;
aDom.setAttribute("href", navLinkDecl(decl.name));
let descDom = liDom.children[1];
descDom.innerHTML = markdown(shortDesc(getAstNode(decl.src).docs));
descDom.innerHTML = markdown(shortDesc(docs));
if (i == splitPoint - 1) {
activeList = domListNamespacesRight;
offset = splitPoint;
}
}
}
domListNamespacesLeft.classList.remove("hidden");