From 48f5b21e7cb1da7593a780ffb59394ce18d1113d Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Wed, 9 Oct 2019 00:24:58 -0400
Subject: [PATCH] generated docs: functions in a table with descriptions

---
 lib/std/special/docs/index.html |  11 ++-
 lib/std/special/docs/main.js    | 114 +++++++++++++++++++++-----------
 2 files changed, 83 insertions(+), 42 deletions(-)

diff --git a/lib/std/special/docs/index.html b/lib/std/special/docs/index.html
index fc78cdaf5d..2508308ced 100644
--- a/lib/std/special/docs/index.html
+++ b/lib/std/special/docs/index.html
@@ -158,10 +158,13 @@
         vertical-align: top;
       }
 
-      #sectGlobalVars td {
+      #sectGlobalVars td, #sectFns td {
         vertical-align: top;
         margin: 0;
         padding: 0.5em;
+        max-width: 20em;
+        text-overflow: ellipsis;
+        overflow-x: hidden;
       }
 
       .tok-kw {
@@ -327,8 +330,10 @@
     </div>
     <div id="sectFns" class="hidden">
       <h2>Functions</h2>
-      <ul id="listFns">
-      </ul>
+      <table>
+        <tbody id="listFns">
+        </tbody>
+      </table>
     </div>
     <div id="sectErrSets" class="hidden">
       <h2>Error Sets</h2>
diff --git a/lib/std/special/docs/main.js b/lib/std/special/docs/main.js
index 63993082b3..5d6e006748 100644
--- a/lib/std/special/docs/main.js
+++ b/lib/std/special/docs/main.js
@@ -191,30 +191,7 @@
     }
 
     function renderFn(fnDecl) {
-        var typeObj = zigAnalysis.types[fnDecl.type];
-        var protoHtml = '<span class="tok-kw">fn</span> <span class="tok-fn">'
-            + escapeHtml(fnDecl.name) + '</span>(';
-        if (typeObj.args != null) {
-            for (var i = 0; i < typeObj.args.length; i += 1) {
-                if (i != 0) {
-                    protoHtml += ', ';
-                }
-                var argTypeIndex = typeObj.args[i];
-                if (argTypeIndex != null) {
-                    protoHtml += typeIndexName(argTypeIndex, true, true);
-                } else {
-                    protoHtml += '<span class="tok-kw">var</span>';
-                }
-            }
-        }
-
-        protoHtml += ') ';
-        if (typeObj.ret != null) {
-            protoHtml += typeIndexName(typeObj.ret, true, true, fnDecl.value);
-        } else {
-            protoHtml += '<span class="tok-kw">var</span>';
-        }
-        domFnProtoCode.innerHTML = protoHtml;
+        domFnProtoCode.innerHTML = typeIndexName(fnDecl.type, true, true, fnDecl);
 
         var docsSource = null;
         var srcNode = zigAnalysis.astNodes[fnDecl.src];
@@ -222,6 +199,7 @@
             docsSource = srcNode.docs;
         }
 
+        var typeObj = zigAnalysis.types[fnDecl.type];
         var errSetTypeIndex = null;
         if (typeObj.ret != null) {
             var retType = zigAnalysis.types[typeObj.ret];
@@ -409,24 +387,24 @@
         }
     }
 
-    function typeIndexName(typeIndex, wantHtml, wantLink, fnIndex) {
+    function typeIndexName(typeIndex, wantHtml, wantLink, fnDecl, skipFnName) {
         var typeObj = zigAnalysis.types[typeIndex];
         if (wantLink) {
             var declIndex = getCanonTypeDecl(typeIndex);
             var declPath = getCanonDeclPath(declIndex);
             var haveLink = declPath != null;
-            var typeNameHtml = typeName(typeObj, true, !haveLink, fnIndex);
+            var typeNameHtml = typeName(typeObj, true, !haveLink, fnDecl, skipFnName);
             if (haveLink) {
                 return '<a href="' + navLink(declPath.pkgNames, declPath.declNames) + '">' + typeNameHtml + '</a>';
             } else {
                 return typeNameHtml;
             }
         } else {
-            return typeName(typeObj, wantHtml, false, fnIndex);
+            return typeName(typeObj, wantHtml, false, fnDecl, skipFnName);
         }
     }
 
-    function typeName(typeObj, wantHtml, wantSubLink, fnIndex) {
+    function typeName(typeObj, wantHtml, wantSubLink, fnDecl, skipFnName) {
         switch (typeObj.kind) {
             case typeKindPtrId:
                 var name = "";
@@ -537,12 +515,48 @@
             case typeKindErrUnionId:
                 var errSetTypeObj = zigAnalysis.types[typeObj.err];
                 var payloadHtml = typeIndexName(typeObj.payload, wantHtml, wantSubLink, null);
-                if (errSetTypeObj.fn != null && errSetTypeObj.fn == fnIndex) {
+                if (fnDecl != null && errSetTypeObj.fn === fnDecl.value) {
                     // function index parameter supplied and this is the inferred error set of it
                     return "!" + payloadHtml;
                 } else {
                     return typeIndexName(typeObj.err, wantHtml, wantSubLink, null) + "!" + payloadHtml;
                 }
+            case typeKindFnId:
+                var payloadHtml = "";
+                if (wantHtml) {
+                    payloadHtml += '<span class="tok-kw">fn</span>';
+                    if (fnDecl != null && !skipFnName) {
+                        payloadHtml += ' <span class="tok-fn">' + escapeHtml(fnDecl.name) + '</span>';
+                    }
+                } else {
+                    payloadHtml += 'fn'
+                }
+                payloadHtml += '(';
+                if (typeObj.args != null) {
+                    for (var i = 0; i < typeObj.args.length; i += 1) {
+                        if (i != 0) {
+                            payloadHtml += ', ';
+                        }
+                        var argTypeIndex = typeObj.args[i];
+                        if (argTypeIndex != null) {
+                            payloadHtml += typeIndexName(argTypeIndex, wantHtml, wantSubLink);
+                        } else if (wantHtml) {
+                            payloadHtml += '<span class="tok-kw">var</span>';
+                        } else {
+                            payloadHtml += 'var';
+                        }
+                    }
+                }
+
+                payloadHtml += ') ';
+                if (typeObj.ret != null) {
+                    payloadHtml += typeIndexName(typeObj.ret, wantHtml, wantSubLink, fnDecl);
+                } else if (wantHtml) {
+                    payloadHtml += '<span class="tok-kw">var</span>';
+                } else {
+                    payloadHtml += 'var';
+                }
+                return payloadHtml;
             default:
                 if (wantHtml) {
                     return escapeHtml(typeObj.name);
@@ -652,13 +666,28 @@
         }
 
         if (fnsList.length !== 0) {
-            resizeDomList(domListFns, fnsList.length, '<li><a href="#"></a></li>');
+            resizeDomList(domListFns, fnsList.length,
+                '<tr><td><a href="#"></a></td><td></td><td></td></tr>');
             for (var i = 0; i < fnsList.length; i += 1) {
-                var liDom = domListFns.children[i];
-                var aDom = liDom.children[0];
                 var decl = fnsList[i];
-                aDom.textContent = decl.name;
-                aDom.setAttribute('href', navLinkDecl(decl.name));
+                var trDom = domListFns.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, decl, true);
+
+                var docs = zigAnalysis.astNodes[decl.src].docs;
+                if (docs != null) {
+                    tdDesc.innerHTML = shortDescMarkdown(docs);
+                } else {
+                    tdDesc.textContent = "";
+                }
             }
             domSectFns.classList.remove("hidden");
         }
@@ -677,24 +706,25 @@
         }
 
         if (varsList.length !== 0) {
-            resizeDomList(domListGlobalVars, varsList.length, '<tr><td></td><td></td><td></td></tr>');
+            resizeDomList(domListGlobalVars, varsList.length,
+                '<tr><td><a href="#"></a></td><td></td><td></td></tr>');
             for (var i = 0; i < varsList.length; i += 1) {
                 var decl = varsList[i];
                 var trDom = domListGlobalVars.children[i];
-                var innerHtml = "";
 
                 var tdName = trDom.children[0];
+                var tdNameA = tdName.children[0];
                 var tdType = trDom.children[1];
                 var tdDesc = trDom.children[2];
 
-                tdName.innerHTML = '<a href="' +
-                    navLinkDecl(decl.name) + '">' + escapeHtml(decl.name) + '</a>';
+                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 = markdown(docs);
+                    tdDesc.innerHTML = shortDescMarkdown(docs);
                 } else {
                     tdDesc.textContent = "";
                 }
@@ -923,6 +953,12 @@
         });
     }
 
+    function shortDescMarkdown(docs) {
+        var parts = docs.trim().split("\n");
+        var firstLine = parts[0];
+        return markdown(firstLine);
+    }
+
     function markdown(mdText) {
         // TODO implement more
         return escapeHtml(mdText);