xmldoc comment fixes

Author: Thorium

docs/content/_template.html

@@ -110,6 +110,7 @@ <H1 style="font-size: 24px;">{{fsdocs-collection-name}}</H1>
     </div>
 </dialog>
 <script type="module" src="{{root}}content/fsdocs-tips.js"></script>
+<script type="module" src="{{root}}content/fsdocs-xmldoc-tips.js"></script>
 <script type="module" src="{{root}}content/fsdocs-theme-toggle.js"></script>
 <script type="module" src="{{root}}content/fsdocs-theme.js"></script>
 <script type="module" src="{{root}}content/fsdocs-search.js"></script>

docs/content/content/fsdocs-custom.css

@@ -345,7 +345,7 @@ blockquote {
 
 #content pre.fssnip code {
     font: 0.86rem 'Fira Code Fixed', monospace;
-    font-weight: 600;
+    font-weight: 500;
 }
 
 #content table.pre {
@@ -553,7 +553,7 @@ blockquote {
 }
 /* keywords */
 #content span.k {
-    color: #1f4ee9;
+    color: #4878f0;
 }
 /* comment */
 #content span.c {
@@ -597,7 +597,6 @@ div.fsdocs-tip {
     border-radius: 4px;
     font: 0.85rem 'Fira Code Fixed', monospace;
     padding: 6px 8px 6px 8px;
-    display: none;
     color: #d1d1d1;
     pointer-events: none;
 }
@@ -607,6 +606,31 @@ div.fsdocs-tip {
         font: 0.85rem 'Fira Code Fixed', monospace;
     }
 
+/* XML doc in a tool tip, rendered by fsdocs-xmldoc-tips.js */
+div.fsdocs-tip-doc {
+    margin-top: 6px;
+    padding-top: 6px;
+    border-top: 1px solid #5f7478;
+    white-space: normal;
+}
+
+div.fsdocs-tip-doc-summary {
+    color: #f0d98c;
+}
+
+div.fsdocs-tip-doc-remarks,
+div.fsdocs-tip-doc-param {
+    margin-top: 4px;
+}
+
+span.fsdocs-tip-doc-name {
+    color: #9cdcfe;
+}
+
+div.fsdocs-tip-doc code {
+    color: #ffffff;
+}
+
 #content code {
     color: #8c938c
 }

docs/content/content/fsdocs-xmldoc-tips.js

@@ -0,0 +1,69 @@
+// fsdocs puts a member's XML doc into its tooltip as raw text, tags included.
+// This renders the tags: the summary in its own colour, one line per parameter, the return value, and
+// <see cref="..."/> / <paramref name="..."/> as the name they refer to.
+
+const docTag = /<\/?(summary|param|returns|remarks|exception|typeparam|see|paramref|typeparamref|para|c|code)\b/;
+
+function refName(el) {
+    const name = el.getAttribute("cref") || el.getAttribute("name") || el.getAttribute("langword") || el.textContent;
+    return name.replace(/^[A-Z]:/, "");
+}
+
+function inline(node, target) {
+    for (const child of node.childNodes) {
+        if (child.nodeType === Node.TEXT_NODE) {
+            target.append(child.textContent.replace(/\s+/g, " "));
+        } else if (child.nodeType === Node.ELEMENT_NODE) {
+            const tag = child.localName;
+            if (tag === "see" || tag === "seealso" || tag === "paramref" || tag === "typeparamref" || tag === "c" || tag === "code") {
+                const code = document.createElement("code");
+                code.textContent = child.textContent.trim() || refName(child);
+                target.append(code);
+            } else {
+                inline(child, target);
+            }
+        }
+    }
+}
+
+function line(cls, label, el) {
+    const body = document.createDocumentFragment();
+    inline(el, body);
+    body.normalize();
+    if (body.firstChild?.nodeType === Node.TEXT_NODE) body.firstChild.textContent = body.firstChild.textContent.trimStart();
+    if (body.lastChild?.nodeType === Node.TEXT_NODE) body.lastChild.textContent = body.lastChild.textContent.trimEnd();
+    const div = document.createElement("div");
+    div.className = cls;
+    if (label) {
+        const name = document.createElement("span");
+        name.className = "fsdocs-tip-doc-name";
+        name.textContent = label;
+        div.append(name, " ");
+    }
+    div.append(body);
+    return div;
+}
+
+function render(text) {
+    const xml = new DOMParser().parseFromString(`<doc>${text}</doc>`, "application/xml");
+    if (xml.getElementsByTagName("parsererror").length > 0) return null;
+    const doc = document.createElement("div");
+    doc.className = "fsdocs-tip-doc";
+    for (const el of xml.documentElement.children) {
+        switch (el.localName) {
+            case "summary": doc.append(line("fsdocs-tip-doc-summary", null, el)); break;
+            case "remarks": doc.append(line("fsdocs-tip-doc-remarks", null, el)); break;
+            case "param":
+            case "typeparam": doc.append(line("fsdocs-tip-doc-param", el.getAttribute("name") + ":", el)); break;
+            case "returns": doc.append(line("fsdocs-tip-doc-param", "Returns:", el)); break;
+            case "exception": doc.append(line("fsdocs-tip-doc-param", "Throws " + refName(el) + ":", el)); break;
+        }
+    }
+    return doc.childNodes.length > 0 ? doc : null;
+}
+
+for (const em of document.querySelectorAll("div.fsdocs-tip > em")) {
+    if (!docTag.test(em.textContent)) continue;
+    const doc = render(em.textContent);
+    if (doc) em.replaceWith(doc);
+}