From c481510c99ab29903350a834810bdcac32dbd9ea Mon Sep 17 00:00:00 2001
From: Loris Cro <kappaloris@gmail.com>
Date: Wed, 20 Sep 2023 19:17:00 +0200
Subject: [PATCH] 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.
---
 lib/docs/main.js | 52 ++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 44 insertions(+), 8 deletions(-)

diff --git a/lib/docs/main.js b/lib/docs/main.js
index 87f3f381a1..4285c2288b 100644
--- a/lib/docs/main.js
+++ b/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");