zig

commit bc393eefa1d80e7e85735d9ccbde13fb52144fcd (tree)
parent d15a71afc95f148966be2f5fd9f66b8396e8293d
Author: Andrew Kelley <andrew@ziglang.org>
Date:   Thu, 10 Oct 2019 19:21:56 -0400

generated docs: better rendering of unknown decls

Diffstat:
M
lib/std/special/docs/index.html
 | 
15
+++++++++++----
M
lib/std/special/docs/main.js
 | 
25
++++++++++++++++++++-----

2 files changed, 31 insertions(+), 9 deletions(-)
diff --git a/lib/std/special/docs/index.html b/lib/std/special/docs/index.html
@@ -289,6 +289,17 @@
       <pre id="fnProtoCode"></pre>
     </div>
     <h1 id="hdrName" class="hidden"></h1>
+    <div id="fnExamples" class="hidden"></div>
+    <div id="fnNoExamples" class="hidden">
+      <p>This function is not tested or referenced.</p>
+    </div>
+    <div id="declNoRef" class="hidden">
+      <p>
+      This declaration is not tested or referenced, and it has therefore not been included in
+      semantic analysis, which means the only documentation available is whatever is in the
+      doc comments.
+      </p>
+    </div>
     <div id="fnDocs" class="hidden"></div>
     <div id="sectFnErrors" class="hidden">
       <h2>Errors</h2>
@@ -297,10 +308,6 @@
       </div>
       <div id="tableFnErrors"><dl id="listFnErrors"></dl></div>
     </div>
-    <div id="fnExamples" class="hidden"></div>
-    <div id="fnNoExamples" class="hidden">
-      <p>This function is not tested or referenced.</p>
-    </div>
     <div id="sectSearchResults" class="hidden">
       <h2>Search Results</h2>
       <ul id="listSearchResults"></ul>
diff --git a/lib/std/special/docs/main.js b/lib/std/special/docs/main.js
@@ -27,6 +27,7 @@
     var domFnErrorsAnyError = document.getElementById("fnErrorsAnyError");
     var domFnExamples = document.getElementById("fnExamples");
     var domFnNoExamples = document.getElementById("fnNoExamples");
+    var domDeclNoRef = document.getElementById("declNoRef");
     var domSearch = document.getElementById("search");
     var domSectSearchResults = document.getElementById("sectSearchResults");
     var domListSearchResults = document.getElementById("listSearchResults");
@@ -112,6 +113,7 @@
         domSectFnErrors.classList.add("hidden");
         domFnExamples.classList.add("hidden");
         domFnNoExamples.classList.add("hidden");
+        domDeclNoRef.classList.add("hidden");
         domFnErrorsAnyError.classList.add("hidden");
         domTableFnErrors.classList.add("hidden");
         domSectGlobalVars.classList.add("hidden");
@@ -160,7 +162,12 @@
         renderNav();
 
         var lastDecl = curNav.declObjs[curNav.declObjs.length - 1];
-        if (lastDecl.kind === 'var') {
+        if (lastDecl.pubDecls != null) {
+            renderContainer(lastDecl);
+        }
+        if (lastDecl.kind == null) {
+            return renderUnknownDecl(lastDecl);
+        } else if (lastDecl.kind === 'var') {
             return renderVar(lastDecl);
         } else if (lastDecl.kind === 'const' && lastDecl.type != null) {
             var typeObj = zigAnalysis.types[lastDecl.type];
@@ -169,13 +176,21 @@
             } else {
                 return renderValue(lastDecl);
             }
-        }
-        if (lastDecl.kind != null) {
+        } else {
             renderType(lastDecl);
         }
-        if (lastDecl.pubDecls != null) {
-            renderContainer(lastDecl);
+    }
+
+    function renderUnknownDecl(decl) {
+        domDeclNoRef.classList.remove("hidden");
+
+        var docs = zigAnalysis.astNodes[decl.src].docs;
+        if (docs != null) {
+            domFnDocs.innerHTML = markdown(docs);
+        } else {
+            domFnDocs.innerHTML = '<p>There are no doc comments for this declaration.</p>';
         }
+        domFnDocs.classList.remove("hidden");
     }
 
     function typeIsErrSet(typeIndex) {