From 6d54e8fc3c41247dc3fa5bd399733b629e9d621d Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Wed, 9 Oct 2019 18:08:11 -0400
Subject: [PATCH] generated docs: render values

also fix pressing enter in search box before search finishes

closes #3409
---
 lib/std/math.zig                |   3 +
 lib/std/special/docs/index.html |   9 +-
 lib/std/special/docs/main.js    | 159 +++++++++++++++++++++++---------
 3 files changed, 127 insertions(+), 44 deletions(-)

diff --git a/lib/std/math.zig b/lib/std/math.zig
index e47021512e..ee30cb9758 100644
--- a/lib/std/math.zig
+++ b/lib/std/math.zig
@@ -4,7 +4,10 @@ const TypeId = builtin.TypeId;
 const assert = std.debug.assert;
 const testing = std.testing;
 
+/// Euler's number (e)
 pub const e = 2.71828182845904523536028747135266249775724709369995;
+
+/// Archimedes' constant (π)
 pub const pi = 3.14159265358979323846264338327950288419716939937510;
 
 // From a small c++ [program using boost float128](https://github.com/winksaville/cpp_boost_float128)
diff --git a/lib/std/special/docs/index.html b/lib/std/special/docs/index.html
index e7a57137e5..ec226f220b 100644
--- a/lib/std/special/docs/index.html
+++ b/lib/std/special/docs/index.html
@@ -156,7 +156,7 @@
         font-weight: bold;
       }
 
-      #sectGlobalVars td, #sectFns td, #sectFields td {
+      td {
         vertical-align: top;
         margin: 0;
         padding: 0.5em;
@@ -338,6 +338,13 @@
         </tbody>
       </table>
     </div>
+    <div id="sectValues" class="hidden">
+      <h2>Values</h2>
+      <table>
+        <tbody id="listValues">
+        </tbody>
+      </table>
+    </div>
     <div id="sectErrSets" class="hidden">
       <h2>Error Sets</h2>
       <ul id="listErrSets">
diff --git a/lib/std/special/docs/main.js b/lib/std/special/docs/main.js
index 8d3bdcb172..54203663e0 100644
--- a/lib/std/special/docs/main.js
+++ b/lib/std/special/docs/main.js
@@ -16,6 +16,8 @@
     var domListFields = document.getElementById("listFields");
     var domSectGlobalVars = document.getElementById("sectGlobalVars");
     var domListGlobalVars = document.getElementById("listGlobalVars");
+    var domSectValues = document.getElementById("sectValues");
+    var domListValues = document.getElementById("listValues");
     var domFnProto = document.getElementById("fnProto");
     var domFnProtoCode = document.getElementById("fnProtoCode");
     var domFnDocs = document.getElementById("fnDocs");
@@ -63,6 +65,7 @@
     };
     var curNavSearch = "";
     var curSearchIndex = -1;
+    var imFeelingLucky = false;
 
     var rootIsStd = detectRootIsStd();
 
@@ -111,6 +114,7 @@
         domFnErrorsAnyError.classList.add("hidden");
         domTableFnErrors.classList.add("hidden");
         domSectGlobalVars.classList.add("hidden");
+        domSectValues.classList.add("hidden");
 
         renderTitle();
         renderInfo();
@@ -157,13 +161,13 @@
         var lastDecl = curNav.declObjs[curNav.declObjs.length - 1];
         if (lastDecl.kind === 'var') {
             return renderVar(lastDecl);
-        }
-        if (lastDecl.type != null) {
+        } else if (lastDecl.kind === 'const' && lastDecl.type != null) {
             var typeObj = zigAnalysis.types[lastDecl.type];
             if (typeObj.kind === typeKinds.Fn) {
                 return renderFn(lastDecl);
+            } else {
+                return renderValue(lastDecl);
             }
-            throw new Error("docs for this decl which is not a container");
         }
         if (lastDecl.kind != null) {
             renderType(lastDecl);
@@ -208,7 +212,7 @@
             var retType = zigAnalysis.types[typeObj.ret];
             if (retType.kind === typeKinds.ErrorSet) {
                 errSetTypeIndex = typeObj.ret;
-            } else if (retType.kind === typeKinds.Union) {
+            } else if (retType.kind === typeKinds.ErrorUnion) {
                 errSetTypeIndex = retType.err;
             }
         }
@@ -515,7 +519,7 @@
                         return typeObj.name;
                     }
                 }
-            case typeKinds.Union:
+            case typeKinds.ErrorUnion:
                 var errSetTypeObj = zigAnalysis.types[typeObj.err];
                 var payloadHtml = typeIndexName(typeObj.payload, wantHtml, wantSubLink, null);
                 if (fnDecl != null && errSetTypeObj.fn === fnDecl.value) {
@@ -625,6 +629,19 @@
         return true;
     }
 
+    function renderValue(decl) {
+        domFnProtoCode.innerHTML = '<span class="tok-kw">pub</span> <span class="tok-kw">const</span> ' +
+            escapeHtml(decl.name) + ': ' + typeIndexName(decl.type, true, true);
+
+        var docs = zigAnalysis.astNodes[decl.src].docs;
+        if (docs != null) {
+            domFnDocs.innerHTML = markdown(docs);
+            domFnDocs.classList.remove("hidden");
+        }
+
+        domFnProto.classList.remove("hidden");
+    }
+
     function renderVar(decl) {
         domFnProtoCode.innerHTML = '<span class="tok-kw">pub</span> <span class="tok-kw">var</span> ' +
             escapeHtml(decl.name) + ': ' + typeIndexName(decl.type, true, true);
@@ -644,13 +661,13 @@
         var errSetsList = [];
         var fnsList = [];
         var varsList = [];
+        var valsList = [];
         for (var i = 0; i < container.pubDecls.length; i += 1) {
             var decl = zigAnalysis.decls[container.pubDecls[i]];
             if (decl.kind === 'var') {
                 varsList.push(decl);
                 continue;
-            }
-            if (decl.type != null) {
+            } else if (decl.kind === 'const' && decl.type != null) {
                 if (decl.type == typeTypeId) {
                     if (typeIsErrSet(decl.value)) {
                         errSetsList.push(decl);
@@ -667,25 +684,18 @@
                         } else {
                             fnsList.push(decl);
                         }
+                    } else {
+                        valsList.push(decl);
                     }
                 }
             }
         }
-        typesList.sort(function(a, b) {
-            return operatorCompare(a.name, b.name);
-        });
-        namespacesList.sort(function(a, b) {
-            return operatorCompare(a.name, b.name);
-        });
-        errSetsList.sort(function(a, b) {
-            return operatorCompare(a.name, b.name);
-        });
-        fnsList.sort(function(a, b) {
-            return operatorCompare(a.name, b.name);
-        });
-        varsList.sort(function(a, b) {
-            return operatorCompare(a.name, b.name);
-        });
+        typesList.sort(byNameProperty);
+        namespacesList.sort(byNameProperty);
+        errSetsList.sort(byNameProperty);
+        fnsList.sort(byNameProperty);
+        varsList.sort(byNameProperty);
+        valsList.sort(byNameProperty);
 
         if (typesList.length !== 0) {
             resizeDomList(domListTypes, typesList.length, '<li><a href="#"></a></li>');
@@ -793,6 +803,33 @@
             }
             domSectGlobalVars.classList.remove("hidden");
         }
+
+        if (valsList.length !== 0) {
+            resizeDomList(domListValues, valsList.length,
+                '<tr><td><a href="#"></a></td><td></td><td></td></tr>');
+            for (var i = 0; i < valsList.length; i += 1) {
+                var decl = valsList[i];
+                var trDom = domListValues.children[i];
+
+                var tdName = trDom.children[0];
+                var tdNameA = tdName.children[0];
+                var tdType = trDom.children[1];
+                var tdDesc = trDom.children[2];
+
+                tdNameA.setAttribute('href', navLinkDecl(decl.name));
+                tdNameA.textContent = decl.name;
+
+                tdType.innerHTML = typeIndexName(decl.type, true, true);
+
+                var docs = zigAnalysis.astNodes[decl.src].docs;
+                if (docs != null) {
+                    tdDesc.innerHTML = shortDescMarkdown(docs);
+                } else {
+                    tdDesc.textContent = "";
+                }
+            }
+            domSectValues.classList.remove("hidden");
+        }
     }
 
     function operatorCompare(a, b) {
@@ -840,7 +877,7 @@
         throw new Error("No type 'type' found");
     }
 
-    function onHashChange() {
+    function updateCurNav() {
         curNav = {
             pkgNames: [],
             pkgObjs: [],
@@ -865,10 +902,18 @@
                 curNav.declNames = decodeURIComponent(parts[1]).split(".");
             }
         }
+    }
+
+    function onHashChange() {
+        updateCurNav();
         if (domSearch.value !== curNavSearch) {
             domSearch.value = curNavSearch;
         }
         render();
+        if (imFeelingLucky) {
+            imFeelingLucky = false;
+            activateSelectedResult();
+        }
     }
 
     function findSubDecl(parentType, childName) {
@@ -999,21 +1044,38 @@
         return escapeHtml(mdText);
     }
 
+    function activateSelectedResult() {
+        if (domSectSearchResults.classList.contains("hidden")) {
+            return;
+        }
+
+        var liDom = domListSearchResults.children[curSearchIndex];
+        if (liDom == null && domListSearchResults.children.length !== 0) {
+            liDom = domListSearchResults.children[0];
+        }
+        if (liDom != null) {
+            var aDom = liDom.children[0];
+            location.href = aDom.getAttribute("href");
+            curSearchIndex = -1;
+        }
+        domSearch.blur();
+    }
+
     function onSearchKeyDown(ev) {
         switch (ev.which) {
             case 13:
-                var liDom = domListSearchResults.children[curSearchIndex];
-                if (liDom == null && domListSearchResults.children.length !== 0) {
-                    liDom = domListSearchResults.children[0];
-                }
-                if (liDom != null) {
-                    var aDom = liDom.children[0];
-                    location.href = aDom.getAttribute("href");
-                    curSearchIndex = -1;
-                    ev.preventDefault();
-                    ev.stopPropagation();
-                    return;
-                }
+                // detect if this search changes anything
+                var terms1 = getSearchTerms();
+                startSearch();
+                updateCurNav();
+                var terms2 = getSearchTerms();
+                // we might have to wait for onHashChange to trigger
+                imFeelingLucky = (terms1.join(' ') !== terms2.join(' '));
+                if (!imFeelingLucky) activateSelectedResult();
+
+                ev.preventDefault();
+                ev.stopPropagation();
+                return;
             case 27:
                 domSearch.value = "";
                 domSearch.blur();
@@ -1036,6 +1098,7 @@
                 curSearchIndex = -1;
                 ev.stopPropagation();
                 startAsyncSearch();
+                return;
         }
     }
 
@@ -1090,7 +1153,10 @@
     }
 
     function clearAsyncSearch() {
-        if (searchTimer != null) clearTimeout(searchTimer);
+        if (searchTimer != null) {
+            clearTimeout(searchTimer);
+            searchTimer = null;
+        }
     }
 
     function startAsyncSearch() {
@@ -1098,18 +1164,21 @@
         searchTimer = setTimeout(startSearch, 100);
     }
     function startSearch() {
-        var parts = location.hash.split("?");
+        clearAsyncSearch();
+        var oldHash = location.hash;
+        var parts = oldHash.split("?");
         var newPart2 = (domSearch.value === "") ? "" : ("?" + domSearch.value);
-        if (parts.length === 1) {
-            location.hash = location.hash + newPart2;
-        } else {
-            location.hash = parts[0] + newPart2;
-        }
+        location.hash = (parts.length === 1) ? (oldHash + newPart2) : (parts[0] + newPart2);
+    }
+    function getSearchTerms() {
+        var list = curNavSearch.trim().split(/[ \r\n\t]+/);
+        list.sort();
+        return list;
     }
     function renderSearch() {
         var matchedItems = [];
         var ignoreCase = (curNavSearch.toLowerCase() === curNavSearch);
-        var terms = curNavSearch.split(/[ \r\n\t]+/);
+        var terms = getSearchTerms();
 
         decl_loop: for (var declIndex = 0; declIndex < zigAnalysis.decls.length; declIndex += 1) {
             var canonPath = getCanonDeclPath(declIndex);
@@ -1226,4 +1295,8 @@
         }
         return map;
     }
+
+    function byNameProperty(a, b) {
+        return operatorCompare(a.name, b.name);
+    }
 })();