From ff28e3febc2f020e8082f5a0a537e03c46ed9f6c Mon Sep 17 00:00:00 2001
From: "Zed A. Shaw" <zed.shaw@gmail.com>
Date: Sat, 17 Dec 2022 14:45:36 -0500
Subject: [PATCH] Better visual design with classes separated out.

---
 admin/pages/DocsBrowser.svelte | 57 ++++++++++++++++++++++++----------
 commands/codedoc.js            | 21 ++++++++++++-
 lib/ormish.js                  |  3 ++
 3 files changed, 63 insertions(+), 18 deletions(-)

diff --git a/admin/pages/DocsBrowser.svelte b/admin/pages/DocsBrowser.svelte
index 5f98139..e28ba2e 100644
--- a/admin/pages/DocsBrowser.svelte
+++ b/admin/pages/DocsBrowser.svelte
@@ -60,25 +60,40 @@
     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 {
+    border-top: 1px solid var(--value5);
+    padding: 0.5rem;
+  }
+
+  export.member {
+    padding-left: 1.5rem;
+  }
+
+  export.class-def {
+    background-color: var(--value6);
+  }
+
   export > heading {
     display: flex;
     flex-direction: column;
-    background-color: var(--color-bg-secondary);
-    border: 1px solid var(--value3);
     width: 100%;
-    padding: 0.5rem;
+    margin-bottom: 1rem;
+    font-weight: 600;
   }
 
-  export > heading h4 {
+  export > heading h4,
+  export > heading h2,
+  export > heading h1
+  {
+    margin-top: 0.5rem;
     font-family: var(--font-family);
-    margin: 0px !important;
+    font-weight: 900;
   }
 
   export > heading meta-data {
@@ -88,18 +103,20 @@
     grid-template-rows: auto;
   }
 
-  export {
-    margin-top: 1rem;
-  }
-
   export > info {
     display: block;
-    padding: 0.5rem;
+    padding-top: 0.5rem;
   }
 
   export > info commment {
     display: block;
   }
+
+  module-header {
+    padding: 0.5rem;
+    background-color: var(--color-bg-inverted);
+    color: var(--color-text-inverted);
+  }
 </style>
 
 
@@ -114,13 +131,19 @@
   </sidebar>
 
   <right>
-    <h1>{ url }</h1>
-    {#if docs_data}
+      {#if docs_data}
+      <module-header>
+        <h1>{ url }</h1>
+        {#if docs_data.comment}
+          {@html docs_data.comment}
+        {/if}
+      </module-header>
+
       {#each docs_data.exports as exp}
         {#if exp.isa === "class"}
-          <export>
+          <export class="class-def">
           <heading>
-            <h2>Class: { exp.name }</h2>
+            <h2>class { exp.name }</h2>
             <Code content={ exp.code } language="javascript" />
           </heading>
           <comment>
@@ -131,7 +154,7 @@
           </export>
 
           {#each exp.methods as member}
-            <export>
+            <export class="member">
               <heading>
                 <h4>{ member.name }</h4>
                 <meta-data>
@@ -155,7 +178,7 @@
         {:else}
           <export>
             <heading>
-              <h4> {exp.name}</h4>
+              <h4>{exp.name}</h4>
               <meta-data>
                 {docs_data.source}:{ exp.line_start }
                 <em>{ exp.isa }</em>
diff --git a/commands/codedoc.js b/commands/codedoc.js
index ba00f61..f0807e6 100644
--- a/commands/codedoc.js
+++ b/commands/codedoc.js
@@ -163,7 +163,7 @@ class ParseWalker {
     }
   }
 
-  /**
+  /*
    Find the nearest comment to this line, giving
    about 2 lines of slack.
    */
@@ -179,6 +179,21 @@ class ParseWalker {
     return undefined;
   }
 
+
+  /*
+   Returns the first comment as the file's main doc comment, or undefined if there isn't one.
+   */
+  file_comment() {
+    const comment = this.comments[0];
+
+    if(comment && comment.start === 1) {
+      // kind of a hack, but find_comment will find this now
+      return this.find_comment(comment.end + 1);
+    } else {
+      return undefined;
+    }
+  }
+
   handle_export(_node) {
     switch(_node.declaration.type) {
       case "ClassDeclaration":
@@ -227,9 +242,13 @@ const parse_source = (source) => {
     ExportNamedDeclaration: (_node) => walker.handle_export(_node),
   });
 
+  let comment = walker.file_comment();
+
   return {
     // normalize to / even on windows
     source: source.replaceAll("\\", "/"),
+    // find the first comment for the file's comment
+    comment,
     exports: walker.exported,
     orphan_comments: walker.comments.filter(c => !c.found)
   };
diff --git a/lib/ormish.js b/lib/ormish.js
index 3541c58..062b835 100644
--- a/lib/ormish.js
+++ b/lib/ormish.js
@@ -1,3 +1,6 @@
+/*
+ The ORMish object-relational-mapping-ish library for knex. It's just enough ORM added to knex to be useful, and anything else you need can be done with knex.
+ */
 import config from '../knexfile.cjs';
 import knexConfig from 'knex';
 import assert from 'assert';