From 564d6c4960018020913d3a2883cdd028f841af20 Mon Sep 17 00:00:00 2001
From: Loris Cro <kappaloris@gmail.com>
Date: Thu, 10 Feb 2022 19:30:04 +0100
Subject: [PATCH] autodocs: improve function rendering

---
 lib/docs/main.js | 397 ++++++++++++++++++++++++++---------------------
 1 file changed, 221 insertions(+), 176 deletions(-)

diff --git a/lib/docs/main.js b/lib/docs/main.js
index 6184bb5b9b..a937fc98e3 100644
--- a/lib/docs/main.js
+++ b/lib/docs/main.js
@@ -118,6 +118,20 @@
     function declContainsType(x){
         console.assert("value" in x);
 
+
+    }
+
+    function typeShorthandName(type) {
+        var name = type.name;
+        if (type.kind === typeKinds.Struct) {
+            name = "struct";
+        } else if (type.kind === typeKinds.Enum) {
+            name = "enum";
+        } else if (type.kind === typeKinds.Union) {
+            name= "union";
+        }
+
+        return name
     }
 
     function typeKindIsContainer(typeKind) {
@@ -169,7 +183,7 @@
             }
 
             if ("struct" in decl.value) {
-                 return resolveTypeRefToTypeId(decl.value.struct.typeRef);
+                return resolveTypeRefToTypeId(decl.value.struct.typeRef);
             }
 
             console.log("TODO: handle in `resolveDeclValueTypeId` more cases: ", decl);
@@ -251,7 +265,7 @@
 
             var childDeclValue = resolveValue(childDecl.value);
             if ("type" in childDeclValue &&
-                 zigAnalysis.types[childDeclValue.type].kind !== typeKinds.Fn){
+                zigAnalysis.types[childDeclValue.type].kind !== typeKinds.Fn){
                 if (i + 1 === curNav.declNames.length) {
                     curNav.declObjs.push(zigAnalysis.types[childDeclValue.type]);
                     break;
@@ -416,12 +430,29 @@
             }
             var divDom = domListParams.children[domIndex];
             domIndex += 1;
-            var value = resolveValue(typeObj.params[i]);
-            console.assert("type" in value);
-            var argTypeIndex = value.type;
+
+
+            var value = typeObj.params[i];
+            var valueType = resolveValue(value);
+            console.assert("type" in valueType);
+            var argTypeIndex = valueType.type;
             var html = '<pre>' + escapeHtml(fieldNode.name) + ": ";
             if (isVarArgs && i === typeObj.params.length - 1) {
                 html += '...';
+            } else if ("declRef" in value) {
+                var decl = zigAnalysis.decls[value.declRef];
+                var val = resolveValue(decl.value);
+                var valType = zigAnalysis.types[argTypeIndex];
+
+                var valTypeName = typeShorthandName(valType);
+
+                html += '<a href="'+navLinkDecl(decl.name)+'">';
+                html += '<span class="tok-kw" style="color:lightblue;">' + decl.name + '</span>';
+                html += '</a>';
+                html += ' ('+ valTypeName +')';
+            } else if ("type" in value) {
+                var name = zigAnalysis.types[value.type].name;
+                html += '<span class="tok-kw">' + name + '</span>';
             } else if (argTypeIndex != null) {
                 html += typeIndexName(argTypeIndex, true, true);
             } else {
@@ -558,12 +589,12 @@
         var callName = declNamesCopy.pop();
 
         callName += '(';
-        for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
-            if (arg_i !== 0) callName += ',';
-            var argObj = callObj.args[arg_i];
-            callName += getValueText(argObj.type, argObj.value, false, false);
-        }
-        callName += ')';
+            for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
+                if (arg_i !== 0) callName += ',';
+                var argObj = callObj.args[arg_i];
+                callName += getValueText(argObj.type, argObj.value, false, false);
+            }
+            callName += ')';
 
         declNamesCopy.push(callName);
         return navLink(curNav.pkgNames, declNamesCopy);
@@ -633,15 +664,15 @@
 
         // TODO make these links work
         //var html = '<a href="' + navLinkCall(callObj) + '">' + escapeHtml(fnDecl.name) + '</a>(';
-        var html = escapeHtml(fnDecl.name) + '(';
-        for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
-            if (arg_i !== 0) html += ', ';
-            var argObj = callObj.args[arg_i];
-            html += getValueText(argObj.type, argObj.value, true, true);
+            var html = escapeHtml(fnDecl.name) + '(';
+                for (var arg_i = 0; arg_i < callObj.args.length; arg_i += 1) {
+                    if (arg_i !== 0) html += ', ';
+                    var argObj = callObj.args[arg_i];
+                    html += getValueText(argObj.type, argObj.value, true, true);
+                }
+                html += ')';
+            return html;
         }
-        html += ')';
-        return html;
-    }
 
     function getValueText(typeIndex, value, wantHtml, wantLink) {
         var typeObj = zigAnalysis.types[typeIndex];
@@ -677,7 +708,7 @@
             case typeKinds.Optional:
                 return "?" + typeIndexName(typeObj.child, wantHtml, wantSubLink, fnDecl, linkFnNameDecl);
             case typeKinds.Pointer:
-                var name = "";
+                    var name = "";
                 switch (typeObj.len) {
                     case pointerSizeEnum.One:
                     default:
@@ -832,72 +863,86 @@
                     payloadHtml += 'fn'
                 }
                 payloadHtml += '(';
-                if (typeObj.params) {
-                    var fields = null;
-                    var isVarArgs = false;
-                    var fnNode = zigAnalysis.astNodes[fnDecl.src];
-                    fields = fnNode.fields;
-                    isVarArgs = fnNode.varArgs;
+                    if (typeObj.params) {
+                        var fields = null;
+                        var isVarArgs = false;
+                        var fnNode = zigAnalysis.astNodes[fnDecl.src];
+                        fields = fnNode.fields;
+                        isVarArgs = fnNode.varArgs;
 
-                    for (var i = 0; i < typeObj.params.length; i += 1) {
-                        if (i != 0) {
-                            payloadHtml += ', ';
-                        }
+                        for (var i = 0; i < typeObj.params.length; i += 1) {
+                            if (i != 0) {
+                                payloadHtml += ', ';
+                            }
+                            var value = typeObj.params[i];
+                            var paramValue = resolveValue(value);
+                            console.assert("type" in paramValue);
+                            var argTypeIndex = paramValue.type;
 
-                        var paramValue = resolveValue(typeObj.params[i]);
-                        console.assert("type" in paramValue);
-                        var argTypeIndex = paramValue.type;
 
-                        if (fields != null) {
-                            var paramNode = zigAnalysis.astNodes[fields[i]];
+                            if (fields != null) {
+                                var paramNode = zigAnalysis.astNodes[fields[i]];
 
-                            if (paramNode.varArgs) {
+                                if (paramNode.varArgs) {
+                                    payloadHtml += '...';
+                                    continue;
+                                }
+
+                                if (paramNode.noalias) {
+                                    if (wantHtml) {
+                                        payloadHtml += '<span class="tok-kw">noalias</span> ';
+                                    } else {
+                                        payloadHtml += 'noalias ';
+                                    }
+                                }
+
+                                if (paramNode.comptime) {
+                                    if (wantHtml) {
+                                        payloadHtml += '<span class="tok-kw">comptime</span> ';
+                                    } else {
+                                        payloadHtml += 'comptime ';
+                                    }
+                                }
+
+                                var paramName = paramNode.name;
+                                if (paramName != null) {
+                                    // skip if it matches the type name
+                                    if (argTypeIndex == null || !shouldSkipParamName(argTypeIndex, paramName)) {
+                                        payloadHtml += paramName + ': ';
+                                    }
+                                }
+                            }
+
+                            if (isVarArgs && i === typeObj.args.length - 1) {
                                 payloadHtml += '...';
-                                continue;
-                            }
+                            } else if ("declRef" in value) {
+                                var decl = zigAnalysis.decls[value.declRef];
+                                var val = resolveValue(decl.value);
+                                var valType = zigAnalysis.types[argTypeIndex];
 
-                            if (paramNode.noalias) {
-                                if (wantHtml) {
-                                    payloadHtml += '<span class="tok-kw">noalias</span> ';
-                                } else {
-                                    payloadHtml += 'noalias ';
-                                }
-                            }
+                                var valTypeName = typeShorthandName(valType);
 
-                            if (paramNode.comptime) {
-                                if (wantHtml) {
-                                    payloadHtml += '<span class="tok-kw">comptime</span> ';
-                                } else {
-                                    payloadHtml += 'comptime ';
-                                }
+                                payloadHtml += '<a href="'+navLinkDecl(decl.name)+'">';
+                                payloadHtml += '<span class="tok-kw" style="color:lightblue;">' + decl.name + '</span>';
+                                payloadHtml += '</a>';
+                            } else if ("type" in value) {
+                                var name = zigAnalysis.types[value.type].name;
+                                payloadHtml += '<span class="tok-kw">' + name + '</span>';
+                            } else if (argTypeIndex != null) {
+                                payloadHtml += typeIndexName(argTypeIndex, wantHtml, wantSubLink);
+                            } else if (wantHtml) {
+                                payloadHtml += '<span class="tok-kw">var</span>';
+                            } else {
+                                payloadHtml += 'var';
                             }
-
-                            var paramName = paramNode.name;
-                            if (paramName != null) {
-                                // skip if it matches the type name
-                                if (argTypeIndex == null || !shouldSkipParamName(argTypeIndex, paramName)) {
-                                    payloadHtml += paramName + ': ';
-                                }
-                            }
-                        }
-
-                        if (isVarArgs && i === typeObj.args.length - 1) {
-                            payloadHtml += '...';
-                        } else if (argTypeIndex != null) {
-                            payloadHtml += typeIndexName(argTypeIndex, wantHtml, wantSubLink);
-                        } else if (wantHtml) {
-                            payloadHtml += '<span class="tok-kw">var</span>';
-                        } else {
-                            payloadHtml += 'var';
                         }
                     }
-                }
 
-                var retValue = resolveValue(typeObj.ret);
-                console.assert("type" in retValue);
-                var retTypeIndex = retValue.type;
+                    var retValue = resolveValue(typeObj.ret);
+                    console.assert("type" in retValue);
+                    var retTypeIndex = retValue.type;
 
-                payloadHtml += ') ';
+                    payloadHtml += ') ';
                 if (retTypeIndex != null) {
                     payloadHtml += typeIndexName(retTypeIndex, wantHtml, wantSubLink, fnDecl);
                 } else if (wantHtml) {
@@ -1015,14 +1060,14 @@
                 var next = typeObj.pubDecls[declI];
                 if (prev === next) continue;
                 // TODO instead of showing "examples" as the public declarations,
-                // do logic like this:
+                    // do logic like this:
                 //if (typeof(prev) !== 'object') {
-                //    var newDeclId = zigAnalysis.decls.length;
-                //    prev = clone(zigAnalysis.decls[prev]);
-                //    prev.id = newDeclId;
-                //    zigAnalysis.decls.push(prev);
-                //    containerObj.pubDecls[declI] = prev;
-                //}
+                    //    var newDeclId = zigAnalysis.decls.length;
+                    //    prev = clone(zigAnalysis.decls[prev]);
+                    //    prev.id = newDeclId;
+                    //    zigAnalysis.decls.push(prev);
+                    //    containerObj.pubDecls[declI] = prev;
+                    //}
                 //mergeDecls(prev, next, firstTypeObj, typeObj);
             }
         }
@@ -1067,10 +1112,10 @@
         switch(Object.keys(decl.value)[0]) {
             case "int":
                 declValueText += decl.value.int.value;
-            break;
+                break;
             case "float":
                 declValueText += decl.value.float.value;
-            break;
+                break;
             default:
                 console.log("TODO: renderValue for ", Object.keys(decl.value)[0]);
                 declValueText += "#TODO#";
@@ -1114,32 +1159,33 @@
         var declLen = container.pubDecls ? container.pubDecls.length : 0;
         for (var i = 0; i < declLen; i += 1) {
             var decl = zigAnalysis.decls[container.pubDecls[i]];
-            var declTypeId = resolveDeclValueTypeId(decl);
+            var declValue = resolveValue(decl.value);
 
             if (decl.kind === 'var') {
                 varsList.push(decl);
                 continue;
-            } else if (decl.kind === 'const') {
-                if (declTypeId === typeTypeId) {
-                    if (typeIsErrSet(declTypeId)) {
+            }
+
+            if (decl.kind === 'const') {
+                if (!("type" in declValue)){
+                    valsList.push(decl);
+                } else {
+                    var value = zigAnalysis.types[declValue.type];
+                    var kind = value.kind;
+                    if (kind === typeKinds.Fn) {
+                        //if (allCompTimeFnCallsHaveTypeResult(decl.type, declTypeId)) {
+                       //     typesList.push(decl);
+                        //} else {
+                            fnsList.push(decl);
+                       // }
+
+                    } else  if (typeIsErrSet(declValue.type)) {
                         errSetsList.push(decl);
-                    } else if (typeIsStructWithNoFields(declTypeId)) {
+                    } else if (typeIsStructWithNoFields(declValue.type)) {
                         namespacesList.push(decl);
                     } else {
                         typesList.push(decl);
                     }
-                } else {
-                    var typeKind = zigAnalysis.types[declTypeId].kind;
-                    if (typeKind === typeKinds.Fn) {
-                        // TODO: this is broken but I don't understand functions yet
-                        if (allCompTimeFnCallsHaveTypeResult(decl.type, declTypeId)) {
-                            typesList.push(decl);
-                        } else {
-                            fnsList.push(decl);
-                        }
-                    } else {
-                        valsList.push(decl);
-                    }
                 }
             }
         }
@@ -1202,7 +1248,10 @@
                 var tdFnCode = trDom.children[0];
                 var tdDesc = trDom.children[1];
 
-                tdFnCode.innerHTML = typeIndexName(decl.type, true, true, decl, navLinkDecl(decl.name));
+                var declType = resolveValue(decl.value);
+                console.assert("type" in declType);
+
+                tdFnCode.innerHTML = typeIndexName(declType.type, true, true, decl, navLinkDecl(decl.name));
 
                 var docs = zigAnalysis.astNodes[decl.src].docs;
                 if (docs != null) {
@@ -1238,11 +1287,7 @@
                             console.assert("type" in val);
                             var valType = zigAnalysis.types[val.type];
 
-                            var valTypeName = valType.name;
-                            if (valType.kind === typeKinds.Struct) {
-                                valTypeName = "struct";
-                            }
-
+                            var valTypeName = typeShorthandName(valType);
                             html += '<a href="'+navLinkDecl(decl.name)+'">';
                             html += '<span class="tok-kw" style="color:lightblue;">' + decl.name + '</span>';
                             html += '</a>';
@@ -1430,12 +1475,12 @@
     function computeCanonicalPackagePaths() {
         var list = new Array(zigAnalysis.packages.length);
         // Now we try to find all the packages from root.
-        var rootPkg = zigAnalysis.packages[zigAnalysis.rootPkg];
+            var rootPkg = zigAnalysis.packages[zigAnalysis.rootPkg];
         // Breadth-first to keep the path shortest possible.
-        var stack = [{
-            path: [],
-            pkg: rootPkg,
-        }];
+            var stack = [{
+                path: [],
+                pkg: rootPkg,
+            }];
         while (stack.length !== 0) {
             var item = stack.shift();
             for (var key in item.pkg.table) {
@@ -1534,7 +1579,7 @@
 
         // PHASE 1:
         // Dissect lines and determine the type for each line.
-        // Also computes indentation level and removes unnecessary whitespace
+            // Also computes indentation level and removes unnecessary whitespace
 
         var is_reading_code = false;
         var code_indent = 0;
@@ -1613,20 +1658,20 @@
 
         // PHASE 2:
         // Render HTML from markdown lines.
-        // Look at each line and emit fitting HTML code
+            // Look at each line and emit fitting HTML code
 
         function markdownInlines(innerText, stopChar) {
 
             // inline types:
             // **{INLINE}**       : <strong>
-            // __{INLINE}__       : <u>
-            // ~~{INLINE}~~       : <s>
-            //  *{INLINE}*        : <emph>
-            //  _{INLINE}_        : <emph>
-            //  `{TEXT}`          : <code>
-            //  [{INLINE}]({URL}) : <a>
-            // ![{TEXT}]({URL})   : <img>
-            // [[std;format.fmt]] : <a> (inner link)
+                // __{INLINE}__       : <u>
+                // ~~{INLINE}~~       : <s>
+                //  *{INLINE}*        : <emph>
+                //  _{INLINE}_        : <emph>
+                //  `{TEXT}`          : <code>
+                //  [{INLINE}]({URL}) : <a>
+                // ![{TEXT}]({URL})   : <img>
+                // [[std;format.fmt]] : <a> (inner link)
 
             const formats = [
                 {
@@ -1668,9 +1713,9 @@
                 if (parsing_code && in_code) {
                     if (innerText.substr(i, codetag.length) == codetag) {
                         // remove leading and trailing whitespace if string both starts and ends with one.
-                        if (currentRun[0] == " " && currentRun[currentRun.length - 1] == " ") {
-                            currentRun = currentRun.substr(1, currentRun.length - 2);
-                        }
+                            if (currentRun[0] == " " && currentRun[currentRun.length - 1] == " ") {
+                                currentRun = currentRun.substr(1, currentRun.length - 2);
+                            }
                         flushRun();
                         i += codetag.length - 1;
                         in_code = false;
@@ -1935,7 +1980,7 @@
                 startAsyncSearch();
                 break;
             case "?":
-                ev.preventDefault();
+                    ev.preventDefault();
                 ev.stopPropagation();
                 showHelpModal();
                 break;
@@ -2054,60 +2099,60 @@
         }
     }
 
-    function renderSearchCursor() {
-        for (var i = 0; i < domListSearchResults.children.length; i += 1) {
-            var liDom = domListSearchResults.children[i];
-            if (curSearchIndex === i) {
-                liDom.classList.add("selected");
-            } else {
-                liDom.classList.remove("selected");
-            }
+function renderSearchCursor() {
+    for (var i = 0; i < domListSearchResults.children.length; i += 1) {
+        var liDom = domListSearchResults.children[i];
+        if (curSearchIndex === i) {
+            liDom.classList.add("selected");
+        } else {
+            liDom.classList.remove("selected");
         }
     }
+}
 
-    function indexNodesToFns() {
-        var map = {};
-        for (var i = 0; i < zigAnalysis.fns.length; i += 1) {
-            var fn = zigAnalysis.fns[i];
-            if (typeIsGenericFn(fn.type)) continue;
-            if (map[fn.src] == null) {
-                map[fn.src] = [i];
-            } else {
-                map[fn.src].push(i);
-            }
-        }
-        return map;
-    }
-
-    function indexNodesToCalls() {
-        var map = {};
-        for (var i = 0; i < zigAnalysis.calls.length; i += 1) {
-            var call = zigAnalysis.calls[i];
-            var fn = zigAnalysis.fns[call.fn];
-            if (map[fn.src] == null) {
-                map[fn.src] = [i];
-            } else {
-                map[fn.src].push(i);
-            }
-        }
-        return map;
-    }
-
-    function byNameProperty(a, b) {
-        return operatorCompare(a.name, b.name);
-    }
-
-    function clone(obj) {
-        var res = {};
-        for (var key in obj) {
-            res[key] = obj[key];
-        }
-        return res;
-    }
-
-    function firstObjectKey(obj) {
-        for (var key in obj) {
-            return key;
+function indexNodesToFns() {
+    var map = {};
+    for (var i = 0; i < zigAnalysis.fns.length; i += 1) {
+        var fn = zigAnalysis.fns[i];
+        if (typeIsGenericFn(fn.type)) continue;
+        if (map[fn.src] == null) {
+            map[fn.src] = [i];
+        } else {
+            map[fn.src].push(i);
         }
     }
+    return map;
+}
+
+function indexNodesToCalls() {
+    var map = {};
+    for (var i = 0; i < zigAnalysis.calls.length; i += 1) {
+        var call = zigAnalysis.calls[i];
+        var fn = zigAnalysis.fns[call.fn];
+        if (map[fn.src] == null) {
+            map[fn.src] = [i];
+        } else {
+            map[fn.src].push(i);
+        }
+    }
+    return map;
+}
+
+function byNameProperty(a, b) {
+    return operatorCompare(a.name, b.name);
+}
+
+function clone(obj) {
+    var res = {};
+    for (var key in obj) {
+        res[key] = obj[key];
+    }
+    return res;
+}
+
+function firstObjectKey(obj) {
+    for (var key in obj) {
+        return key;
+    }
+}
 })();