docs: added custom typedoc plugins

.eslintrc.js

@@ -10,4 +10,12 @@ module.exports = {
   env: {
     node: true,
   },
+  overrides: [
+    {
+      files: ["typedoc-plugins/**/*.js"],
+      rules: {
+        "@typescript-eslint/no-var-requires": "off",
+      },
+    },
+  ],
 };

package.json

@@ -15,7 +15,7 @@
     "lint": "tsc --noEmit --pretty && eslint . --ignore-path .gitignore",
     "watch": "parcel watch",
     "build": "parcel build",
-    "generate-docs": "typedoc --plugin typedoc-plugin-markdown --plugin typedoc-plugin-no-inherit --plugin typedoc-plugin-expand-object-like-types --plugin typedoc-plugin-include-example --out docs src/"
+    "generate-docs": "typedoc --plugin typedoc-plugin-markdown --plugin typedoc-plugin-no-inherit --plugin ./typedoc-plugins/expand-object.js --plugin ./typedoc-plugins/include-example --out docs src/"
   },
   "files": [
     "dist/"
@@ -51,7 +51,6 @@
     "parcel": "^2.11.0",
     "prettier": "3.2.4",
     "typedoc": "^0.25.12",
-    "typedoc-plugin-expand-object-like-types": "^0.1.2",
     "typedoc-plugin-include-example": "^1.2.0",
     "typedoc-plugin-markdown": "^3.17.1",
     "typedoc-plugin-no-inherit": "^1.4.0",

typedoc-plugins/expand-object.js

@@ -0,0 +1,106 @@
+const td = require("typedoc");
+
+/** @param {td.Application} app */
+exports.load = function (app) {
+  app.converter.on(
+    td.Converter.EVENT_CREATE_DECLARATION,
+    function (context, reflection) {
+      expandObjectLikeTypes(context, reflection, app);
+    },
+  );
+};
+
+/**
+ * The reflection types affected by this plugin.
+ */
+const TYPES_TO_EXPAND = ["mapped", "intersection", "reference"];
+
+/**
+ * @param {td.Context} context
+ * @param {td.DeclarationReflection} reflection
+ * @param {td.Application} app
+ */
+function expandObjectLikeTypes(context, reflection, app) {
+  const hasInternalModule =
+    app.options.getDeclaration("internalModule") !== undefined;
+  const internalModule = hasInternalModule
+    ? app.options.getValue("internalModule") || "<internal>"
+    : "<internal>";
+
+  if (
+    reflection.kind !== td.ReflectionKind.TypeAlias ||
+    !reflection.type?.type ||
+    !TYPES_TO_EXPAND.includes(reflection.type.type) ||
+    reflection.parent.originalName === internalModule
+  )
+    return;
+
+  const symbol = context.project.getSymbolFromReflection(reflection);
+  const declaration = symbol?.declarations?.[0];
+
+  if (!symbol || !declaration) return; // Will probably never happen in practice
+  const reflectionType = context.checker.getDeclaredTypeOfSymbol(symbol);
+
+  const typeRefl = context
+    .withScope(reflection)
+    .createDeclarationReflection(
+      td.ReflectionKind.TypeLiteral,
+      undefined,
+      undefined,
+      "__type",
+    );
+  context.finalizeDeclarationReflection(typeRefl);
+  const typeContext = context.withScope(typeRefl);
+
+  for (const propertySymbol of reflectionType.getProperties()) {
+    const propertyType =
+      propertySymbol &&
+      context.checker.getTypeOfSymbolAtLocation(propertySymbol, declaration);
+    const resolvedReflection = resolvePropertyReflection(
+      context,
+      reflectionType,
+      propertySymbol,
+    );
+
+    const element = typeContext.createDeclarationReflection(
+      td.ReflectionKind.Property,
+      undefined,
+      undefined,
+      propertySymbol.name,
+    );
+
+    if (resolvedReflection) {
+      element.comment = resolvedReflection.comment;
+      element.flags = resolvedReflection.flags;
+      element.sources = resolvedReflection.sources;
+
+      if (resolvedReflection instanceof td.DeclarationReflection) {
+        element.defaultValue = resolvedReflection.defaultValue;
+      }
+    }
+
+    element.type = typeContext.converter.convertType(typeContext, propertyType);
+    typeContext.finalizeDeclarationReflection(element);
+  }
+
+  reflection.type = new td.ReflectionType(typeRefl);
+}
+
+/**
+ * @param {td.Context} context
+ * @param {td.TypeScript.Type} objectType
+ * @param {td.TypeScript.Symbol} propertySymbol
+ */
+function resolvePropertyReflection(context, objectType, propertySymbol) {
+  const resolvedType = context.checker.getPropertyOfType(
+    objectType,
+    propertySymbol.name,
+  );
+  const resolvedDeclaration = resolvedType?.declarations?.[0];
+  const resolvedSymbol =
+    resolvedDeclaration && context.getSymbolAtLocation(resolvedDeclaration);
+
+  return (
+    resolvedSymbol && context.project.getReflectionFromSymbol(resolvedSymbol)
+  );
+}

typedoc-plugins/include-example.js

@@ -0,0 +1,36 @@
+const { Converter } = require("typedoc");
+const {
+  iterateProjectComments,
+} = require("../node_modules/typedoc-plugin-include-example/src/iterate-project-comments");
+const {
+  findExample,
+} = require("../node_modules/typedoc-plugin-include-example/src/find-example");
+
+function includeExample(comment, example) {
+  comment.summary.push({
+    kind: "code",
+    text: `\n\n### Example\n\`\`\`ts\n${example}\`\`\``,
+  });
+
+  comment.blockTags = comment.blockTags.filter(
+    (tag) => tag.tag !== "@includeExample",
+  );
+}
+
+function processComments(context) {
+  for (const comment of iterateProjectComments(context)) {
+    const example = findExample(comment);
+
+    if (example !== null) {
+      const exampleWithPackageImport = example.replace(
+        /import {(.+)} from "\.\.\/\.\.\/src\/index"/g,
+        'import {$1} from "clarifai-nodejs"',
+      );
+      includeExample(comment, exampleWithPackageImport);
+    }
+  }
+}
+
+exports.load = function (application) {
+  application.converter.on(Converter.EVENT_RESOLVE_BEGIN, processComments);
+};