Add Typedoc setup for integrating generated api docs

docs/_config.yml

@@ -55,6 +55,16 @@ defaults:
     values:
       render_with_liquid: true
 
+nav_external_links:
+  - title: Derby API
+    url: /api
+    hide_icon: true
+    opens_in_new_tab: true
+  - title: Racer API
+    url: https://derbyjs.github.io/racer
+    hide_icon: true
+    opens_in_new_tab: true
+
 # Exclude from processing.
 # The following items will not be processed, by default.
 # Any item listed under the `exclude:` key here will be automatically added to

package.json

@@ -37,6 +37,7 @@
   "scripts": {
     "build": "node_modules/.bin/tsc",
     "checks": "npm run lint && npm test",
+    "docs": "npx typedoc",
     "lint": "npx eslint src/**/*.ts test/**/*.js",
     "lint:ts": "npx eslint src/**/*.ts",
     "lint:fix": "npm run lint:ts -- --fix",
@@ -78,6 +79,9 @@
     "prettier": "^3.0.1",
     "racer": "^v2.0.0-beta.11",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-mdn-links": "^3.1.28",
+    "typedoc-plugin-missing-exports": "^2.2.0",
     "typescript": "~5.1.3"
   },
   "peerDependencies": {

src/templates/contexts.ts

@@ -8,6 +8,9 @@ import { Controller } from '../Controller';
 
 function noop() { }
 
+/**
+ * Properties and methods which are globally inherited for the entire page
+ */
 export class ContextMeta {
   addBinding: (binding: any) => void = noop;
   removeBinding: (binding: any) => void = noop;
@@ -82,6 +85,11 @@ export class Context {
     this._eventModels = null;
   }
 
+  /**
+   * Generate unique Id
+   * 
+   * @returns namespaced Id
+   */
   id() {
     const count = ++this.meta.idCount;
     return this.meta.idNamespace + '_' + count.toString(36);
@@ -136,7 +144,13 @@ export class Context {
     return new Context(this.meta, component, this, this.unbound);
   }
 
-  // Make a context for an item in an each block
+  /**
+   * Make a context for an item in an each block
+   * 
+   * @param expression 
+   * @param item 
+   * @returns new Context
+   */
   eachChild(expression, item) {
     const context = new Context(this.meta, this.controller, this, this.unbound, expression);
     context.item = item;
@@ -210,6 +224,11 @@ export class Context {
     }
   }
 
+  /**
+   * Gets the current `context` view or closest `context.parent` view
+   * 
+   * @returns view
+   */
   getView() {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     let context: Context = this;

src/test-utils/ComponentHarness.ts

@@ -80,7 +80,12 @@ export class ComponentHarness extends EventEmitter {
   document: Document;
   model: RootModel;
   page: PageForHarness;
-
+
+  /**
+   * Creates a `ComponentHarness`.
+   *
+   * If arguments are provided, then `#setup` is called with the arguments.
+   */
   constructor() {
     super();
     this.app = new AppForHarness(this);
@@ -94,15 +99,15 @@ export class ComponentHarness extends EventEmitter {
 
   /** @typedef { {view: {is: string, source?: string}} } InlineComponent */
   /**
- * Sets up the harness with a HTML template, which should contain a `<view is="..."/>` for the
- * component under test, and the components to register for the test.
- *
- * @param {string} source - HTML template for the harness page
- * @param {...(Component | InlineComponent} components - components to register for the test
- *
- * @example
- *   var harness = new ComponentHarness().setup('<view is="dialog"/>', Dialog);
- */
+   * Sets up the harness with a HTML template, which should contain a `<view is="..."/>` for the
+   * component under test, and the components to register for the test.
+   *
+   * @param {string} source - HTML template for the harness page
+   * @param {...(Component | InlineComponent} components - components to register for the test
+   *
+   * @example
+   *   var harness = new ComponentHarness().setup('<view is="dialog"/>', Dialog);
+   */
   setup(source: string, ...components: ComponentConstructor[]) {
     this.app.views.register('$harness', source);
     // Remaining variable arguments are components

typedoc.json

@@ -0,0 +1,17 @@
+{
+    "entryPoints": ["src/index.ts"],
+    "excludeNotDocumented": false,
+    "plugin":[
+      "typedoc-plugin-mdn-links",
+      "typedoc-plugin-missing-exports",
+      "./typedocExcludeUnderscore.mjs"
+    ],
+    "out": "docs/api",
+    "visibilityFilters": {
+      "protected": false,
+      "private": false,
+      "inherited": true,
+      "external": false
+    },
+    "excludePrivate": true
+  }

typedocExcludeUnderscore.mjs

@@ -0,0 +1,30 @@
+import { Converter, ReflectionFlag, ReflectionKind } from "typedoc";
+import camelCase from "camelcase";
+
+/**
+ * @param {Readonly<import('typedoc').Application>} app
+ */
+export function load(app) {
+  /**
+   * Create declaration event handler that sets symbols with underscore-prefixed names
+   * to private to exclude from generated documentation.
+   *
+   * Due to "partial class" style of code in use, otherwise private properties and methods -
+   * prefixed with underscore - are effectively declared public so they can be accessed in other
+   * files used to build class - e.g. Model. This marks anything prefixed with an underscore and
+   * no doc comment as private.
+   *
+   * @param {import('typedoc').Context} context
+   * @param {import('typedoc').DeclarationReflection} reflection
+   */
+  function handleCreateDeclaration(context, reflection) {
+    if (!reflection.name.startsWith('_')) {
+      return;
+    }
+    if (!reflection.comment) {
+      reflection.setFlag(ReflectionFlag.Private);
+    }
+  }
+
+  app.converter.on(Converter.EVENT_CREATE_DECLARATION, handleCreateDeclaration);
+}