From 447dd2fed184bb9b4f000faa9902fa85d5846ba8 Mon Sep 17 00:00:00 2001
From: Ian Shehadeh <ian@shehadeh.net>
Date: Sun, 20 Aug 2023 01:24:17 -0400
Subject: [PATCH] Add inline manifest documentation (#503)

---
 common/manifest.ts | 32 ++++++++++++++++++++++++++++++++
 plugos/types.ts    | 38 ++++++++++++++++++++++++++++++++++----
 2 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/common/manifest.ts b/common/manifest.ts
index 38d0d758..cea96a60 100644
--- a/common/manifest.ts
+++ b/common/manifest.ts
@@ -8,6 +8,13 @@ import { CodeWidgetT } from "../web/hooks/code_widget.ts";
 import { MQHookT } from "../plugos/hooks/mq.ts";
 import { EndpointHookT } from "../plugos/hooks/endpoint.ts";
 
+/** Silverbullet hooks give plugs access to silverbullet core systems. 
+ * 
+ * Hooks are associated with typescript functions through a manifest file.
+ * On various triggers (user enters a slash command, an HTTP endpoint is hit, user clicks, etc) the typescript function is called.
+ * 
+ * related: plugos/type.ts#FunctionDef
+*/
 export type SilverBulletHooks =
   & CommandHookT
   & SlashCommandHookT
@@ -18,15 +25,40 @@ export type SilverBulletHooks =
   & EndpointHookT
   & PlugNamespaceHookT;
 
+/** Syntax extension allow plugs to declaratively add new *inline* parse tree nodes to the markdown parser. */
 export type SyntaxExtensions = {
+  /** A map of node **name** (also called "type"), to parsing and highlighting instructions. Each entry defines a new node. By convention node names (types) are UpperCamelCase (PascalCase).
+   * 
+   * see: plug-api/lib/tree.ts#ParseTree
+   */
   syntax?: { [key: string]: NodeDef };
 };
 
+/** Parsing and highlighting instructions for SyntaxExtension */
 export type NodeDef = {
+  /** An array of possible first characters to begin matching on.
+   * 
+   * **Example**: If this node has the regex '[abc][123]', NodeDef.firstCharacters should be ["a", "b", "c"].
+  */
   firstCharacters: string[];
+
+  /** A regular expression that matches the *entire* syntax, including the first character. */
   regex: string;
+
+  /** CSS styles to apply to the matched text.
+   * 
+   * Key-value pair of CSS key to value:
+   * 
+   * **Example**: `backgroundColor: "rgba(22,22,22,0.07)"`
+   */
   styles: { [key: string]: string };
+
+  /** CSS class name to apply to the matched text */
   className?: string;
 };
 
+/** A plug manifest configures hooks, declares syntax extensions, and describes plug metadata.
+ *
+ * Typically the manifest file is in a plug's root directory, named `${plugName}.plug.yaml`.
+ */
 export type Manifest = plugos.Manifest<SilverBulletHooks> & SyntaxExtensions;
diff --git a/plugos/types.ts b/plugos/types.ts
index 146c595b..e3244571 100644
--- a/plugos/types.ts
+++ b/plugos/types.ts
@@ -1,22 +1,52 @@
 import { System } from "./system.ts";
 import { AssetJson } from "./asset_bundle/bundle.ts";
 
+/** The generic top level of a plug manifest file.
+ * Defines plug metadata and functions.
+ */
 export interface Manifest<HookT> {
+  /** The plug's name. Typically this is the name of the manifest file, without the file extension. */
   name: string;
+
+  /** A list of syscall permissions required for this plug to function.
+   * 
+   * Possible values:
+   * - `fetch`: enables `fetch` function. (see: plug-api/plugos-syscall/fetch.ts, and plug-api/lib/fetch.ts)
+   * - `shell`: enables the `shell.run` syscall. (see: plug-api/plugos-syscall/shell.ts)
+   */
   requiredPermissions?: string[];
+
+  /** A list of files or glob patterns that should be bundled with the plug.
+   * 
+   * These files will be accessible through the `asset.readAsset` function.
+   * 
+   * see: plug-api/plugos-syscall/asset.ts#readAsset
+   */
   assets?: string[] | AssetJson;
+
+  /** A map of function names to definitions. Declared functions are public, and may be associated with various hooks
+   * 
+   * see: common/manifest.ts#SilverBulletHooks
+   */
   functions: {
     [key: string]: FunctionDef<HookT>;
   };
 }
 
+/** Associates hooks with a function. This is the generic base structure, that identifies the function. Hooks are defined by the type parameter. */
 export type FunctionDef<HookT> = {
-  // Read the function from this path and inline it
-  // Format: filename:functionName
+  /** A function path, in the form `${relativeFilename}:${functionName}`.
+   * 
+   * During compilation (see `../build_plugs.ts`) the function is read from the file and inlined into the plug bundle.
+   * 
+   * This field and `FunctionDef.redirect` are mutually exclusive.
+   */
   path?: string;
-  // Reuse an
-  // Format: plugName.functionName
+
+  /** A function from another plug, in the form `${plugName}.${functionName}` that will be attached to the given hooks. */
   redirect?: string;
+
+  /** Environments where this plug is allowed to run, current may be one of "cli", "server", or "client". */
   env?: string;
 } & HookT;