authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-09-20 19:17:00+02:00
committergravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-09-20 19:17:00+02:00
logc481510c99ab29903350a834810bdcac32dbd9ea
tree93d30e203b38f33ea297f9ad46170226c2a40ebb
parenta63a1c5cb9fd31a57e8371e6cba5f316bd3f2a65

autodoc: show more doc comments for namespaces and types

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.

1 files changed, 44 insertions(+), 8 deletions(-)

lib/docs/main.js+44-8
......@@ -3053,8 +3053,21 @@ Happy writing!
30533053 if (typeIsErrSet(declValue.expr.type)) {
30543054 errSetsList.push(decl);
30553055 } else if (typeIsStructWithNoFields(declValue.expr.type)) {
3056 if (getAstNode(decl.src).docs) {
3057 namespacesWithDocsList.push(decl);
3056
3057 let docs = getAstNode(decl.src).docs;
3058 if (!docs) {
3059 // If this is a re-export, try to fetch docs from the actual definition
3060 const { value, seenDecls } = resolveValue(decl.value, true);
3061 if (seenDecls.length > 0) {
3062 const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
3063 docs = getAstNode(definitionDecl.src).docs;
3064 } else {
3065 docs = getAstNode(getType(value.expr.type).src).docs;
3066 }
3067 }
3068
3069 if (docs) {
3070 namespacesWithDocsList.push({decl, docs});
30583071 } else {
30593072 namespacesNoDocsList.push(decl);
30603073 }
......@@ -3068,8 +3081,19 @@ Happy writing!
30683081 if (typeIsErrSet(declValue.expr.type)) {
30693082 errSetsList.push(decl);
30703083 } else if (typeIsStructWithNoFields(declValue.expr.type)) {
3071 if (getAstNode(decl.src).docs) {
3072 namespacesWithDocsList.push(decl);
3084 let docs = getAstNode(decl.src).docs;
3085 if (!docs) {
3086 // If this is a re-export, try to fetch docs from the actual definition
3087 const { value, seenDecls } = resolveValue(decl.value, true);
3088 if (seenDecls.length > 0) {
3089 const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
3090 docs = getAstNode(definitionDecl.src).docs;
3091 } else {
3092 docs = getAstNode(getType(value.expr.type).src).docs;
3093 }
3094 }
3095 if (docs) {
3096 namespacesWithDocsList.push({decl, docs});
30733097 } else {
30743098 namespacesNoDocsList.push(decl);
30753099 }
......@@ -3215,8 +3239,19 @@ Happy writing!
32153239
32163240 let descDom = liDom.children[1];
32173241 let docs = getAstNode(decl.src).docs;
3242 if (!docs) {
3243 // If this is a re-export, try to fetch docs from the actual definition
3244 const { value, seenDecls } = resolveValue(decl.value, true);
3245 if (seenDecls.length > 0) {
3246 const definitionDecl = getDecl(seenDecls[seenDecls.length - 1]);
3247 docs = getAstNode(definitionDecl.src).docs;
3248 } else {
3249 docs = getAstNode(getType(value.expr.type).src).docs;
3250 }
3251 }
3252
32183253 if (docs) {
3219 descDom.innerHTML = markdown(shortDesc(getAstNode(decl.src).docs));
3254 descDom.innerHTML = markdown(shortDesc(docs));
32203255 } else {
32213256 descDom.innerHTML = "<p class='understated'><i>No documentation provided.</i></p>";
32223257 }
......@@ -3241,16 +3276,17 @@ Happy writing!
32413276 for (let i = 0; i < namespacesWithDocsList.length; i += 1) {
32423277 let liDom = activeList.children[i - offset];
32433278 let aDom = liDom.children[0];
3244 let decl = namespacesWithDocsList[i];
3279 let { decl, docs } = namespacesWithDocsList[i];
32453280 aDom.textContent = decl.name;
32463281 aDom.setAttribute("href", navLinkDecl(decl.name));
3282
32473283
32483284 let descDom = liDom.children[1];
3249 descDom.innerHTML = markdown(shortDesc(getAstNode(decl.src).docs));
3285 descDom.innerHTML = markdown(shortDesc(docs));
32503286 if (i == splitPoint - 1) {
32513287 activeList = domListNamespacesRight;
32523288 offset = splitPoint;
3253 }
3289 }
32543290 }
32553291
32563292 domListNamespacesLeft.classList.remove("hidden");