Commit `c481510c99`

Loris Cro <kappaloris@gmail.com>

2023-09-20 19:17:00

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.

master

1 parent a63a1c5

Changed files (1)

lib

docs

main.js

@@ -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");

Commit c481510c99

Commit `c481510c99`