DocsBrowser now works half decent, just need to actually complete the docs on a few samples to work out the more complete look.

admin/pages/DocsBrowser.svelte

@@ -4,6 +4,7 @@
   import { onMount } from 'svelte';
   import Layout from '$/client/Layout.svelte';
   import Icon from '$/client/components/Icon.svelte';
+  import Markdown from '$/client/components/Markdown.svelte';
   import Blockstart from "$/client/components/Blockstart.svelte";
   import Code from "$/client/components/Code.svelte";
   import api from "$/client/api.js";
@@ -18,6 +19,7 @@
 
     docs_data = status === 200 ? data : {};
     url = to_load;
+    console.log(docs_data);
     window.scrollTo(0, 0);
   }
 
@@ -51,18 +53,56 @@
     overflow-y: auto;
   }
 
-  #content {
+  right {
+    display: flex;
+    flex-direction: column;
     min-height: 100vh;
     height: 100vh;
     max-height: 100vh;
     overflow-y: auto;
+    padding: 0.5rem;
+
+    width: calc(100vw - 300px);
+    min-width: calc(100vw - 300px);
+    max-width: calc(100vw - 300px);
+  }
+
+  export > heading {
+    display: flex;
+    flex-direction: column;
+    background-color: var(--color-bg-secondary);
+    border: 1px solid var(--value3);
+    width: 100%;
+    padding: 0.5rem;
+  }
+
+  export > heading h4 {
+    margin: 0px !important;
+  }
+
+  export > heading meta-data {
+    display: grid;
+    gap: 0.5rem;
+    grid-template-columns: repeat(4, 1fr);
+    grid-template-rows: auto;
+  }
+
+  export {
+    margin-top: 1rem;
+  }
+
+  export > info {
+    display: block;
+    padding: 0.5rem;
+  }
+
+  export > info commment {
+    display: block;
   }
 </style>
 
 
 <Layout footer={ false} header={ false } centered={ true } fullscreen={ true }>
-  <Blockstart>
-    <block class="horizontal">
   <sidebar>
   <top><h4><a href="/" use:link><Icon name="chevrons-up" /> Docs</a></h4></top>
   <items>
@@ -72,33 +112,66 @@
   </items>
   </sidebar>
 
-      <right id="content" style="--pad: 0.5rem;">
+  <right>
+    <h1>{ url }</h1>
     {#if docs_data}
       {#each docs_data.exports as exp}
-            <h1>{ url }</h1>
-            <h2>{exp.name}</h2>
+        {#if exp.isa === "class"}
+          <h2>Class: { exp.name }</h2>
+          <comment>
             {#if exp.comment}
-              <pre>
-{ exp.comment.value }
-              </pre>
+              {@html exp.comment}
             {/if}
-            {#if exp.isa === "class"}
-              {#each exp.methods as method}
-                <h4>{ method.name }</h4>
+          </comment>
+          <Code content={ exp.code } language="javascript" />
+
+          {#each exp.methods as member}
+            <export>
+              <heading>
+                <h4>{ member.name }</h4>
+                <meta-data>
+                  {docs_data.source}:{ member.line_start }
+                  <em>{ member.isa }</em>
+                  {#if member.static}<b>static</b>{/if}
+                  {#if member.async}<b>async</b>{/if}
+                  {#if member.generator}<b>generator</b>{/if}
+                </meta-data>
+              </heading>
+              <info>
                 {#if exp.comment}
-                  <pre>
-{ exp.comment.value }
-                  </pre>
+                  <comment>
+                    { @html exp.comment }
+                  </comment>
                 {/if}
-              <Code content={ method.code } language="javascript" />
+                <h4>Signature</h4>
+                <Code content={ member.code } language="javascript" />
+              </info>
+            </export>
           {/each}
         {:else}
+          <export>
+            <heading>
+              <h4> {exp.name}</h4>
+              <meta-data>
+                {docs_data.source}:{ exp.line_start }
+                <em>{ exp.isa }</em>
+                {#if exp.static}<b>static</b>{/if}
+                {#if exp.async}<b>async</b>{/if}
+                {#if exp.generator}<b>generator</b>{/if}
+                </meta-data>
+              </heading>
+            <info>
+              {#if exp.comment}
+                <comment>
+                {@html exp.comment}
+                </comment>
+              {/if}
+              <h4>Signature</h4>
               <Code content={ exp.code } language="javascript" />
+            </info>
+          </export>
         {/if}
       {/each}
     {/if}
   </right>
-    </block>
-  </Blockstart>
 </Layout>
-

client/assert.js

@@ -2,7 +2,7 @@ import { log } from "./logging.js";
 
 /* I can't believe I have to write this just so I can use the assert that should be standard in every javascript. */
 
-class AssertionError extends Error {
+export class AssertionError extends Error {
   /* This is from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
    * which claims you have to do this weird stuff to make your error actually work.
    */

client/fsm.js

@@ -1,7 +1,7 @@
 import assert from "./assert.js";
 import { log } from "./logging.js";
 
-export default class FSM {
+export class FSM {
 
   constructor(data, events) {
     // data is really only for logging/debugging
@@ -51,3 +51,5 @@ export default class FSM {
     return this.state;
   }
 }
+
+export default FSM;

commands/codedoc.js

@@ -3,6 +3,7 @@ import fs from "fs";
 import assert from "assert";
 import logging from '../lib/logging.js';
 import { mkdir, mkdir_to, glob } from "../lib/builderator.js";
+import { create_renderer } from "../lib/docgen.js";
 import path from "path";
 import template from "lodash/template.js";
 import * as acorn from "acorn";
@@ -24,6 +25,15 @@ export const required = [
   ["--output <string>", "Save to file rather than stdout."],
 ]
 
+const RENDERER = create_renderer();
+
+const render_comment = (comment) => {
+  // strip 1 leading space from the comments, if we strip more it'll
+  // mess up formatting in markdown for indentation formats
+  const lines = comment.split(/\n/).map(l => l.replace(/^\s/, ''));
+  return RENDERER.render(lines.join("\n"));
+}
+
 // handy function for checking things are good and aborting
 const check = (test, fail_message) => {
   if(!test) {
@@ -157,7 +167,7 @@ class ParseWalker {
       const distance = c.end - line;
       if(!c.found && distance < 0 && distance > -3) {
         c.found = true;
-        return c;
+        return render_comment(c.value);
       }
     }
 
@@ -249,7 +259,6 @@ export const main = async (source_globs, opts) => {
 
       const name = normalize_name(fname);
 
-
       index[name] = result.exports.map(e => {
         return {isa: e.isa, name: e.name};
       });

lib/builderator.js

@@ -5,8 +5,8 @@ import { log } from "./logging.js";
 import Path from "path";
 import { execSync } from "child_process";
 
-/**
- * Fixes some common problems with fast-glob on windows.
+/*
+ Fixes some common problems with fast-glob on windows.
  */
 export const glob = (path) => {
   if(process.platform === "win32") {
@@ -36,10 +36,16 @@ export const mkdir = (dir) => {
   }
 }
 
-/**
-  * Given any path to a file, makes sure all its directories are in place.
-  *
-  * @param { string } -- path to file
+/*
+ Given any path to a file, makes sure all its directories are in place.
+
+ Example:
+
+ ```javascript
+ console.log("PRINT");
+ ```
+
+ - `param string` -- path to file
  */
 export const mkdir_to = (target) => {
   let dirs = Path.parse(target);
@@ -52,9 +58,10 @@ export const write = (target, data) => {
   fs.writeFileSync(target, data);
 }
 
-/** Like write but does an OS copy after making the target dir. When given a
- * filter it will give the filter function the arguments, let it return contents,
- * then write those instead of a copy.
+/*
+ Like write but does an OS copy after making the target dir. When given a
+ filter it will give the filter function the arguments, let it return contents,
+ then write those instead of a copy.
  */
 export const copy = (src, dest, filter=null) => {
   mkdir_to(dest);

lib/ormish.js

@@ -37,17 +37,17 @@ const load_schema = async () => {
 
 await load_schema();
 
-/**
- * In some cases (like the generic admin) you need to get validation
- * rules but you don't have a specific class to work with.  This function
- * is called by Model.validation and you can call it directly to get rules
- * for a database table.
- *
- * @param name string - the table name.
- * @param rules Object - default rules with empty "" for the rules you want filled in
- * @param all boolean - set this to true if you want everything
- * @param no_id boolean - defaults to true, set false if you also want the id
- * @return Object - the resulting rules to use with Validator
+/*
+ In some cases (like the generic admin) you need to get validation
+ rules but you don't have a specific class to work with.  This function
+ is called by Model.validation and you can call it directly to get rules
+ for a database table.
+
+ + `name string` - the table name.
+ + `rules Object` - default rules with empty "" for the rules you want filled in
+ + `all boolean` - set this to true if you want everything
+ + `no_id boolean` - defaults to true, set false if you also want the id
+ + `return Object` - the resulting rules to use with Validator
  */
 export const validation = (name, rules, all=false, no_id=true) => {
   assert(rules, "rules parameter is required and will be modified");