feat: update service client documentation generator

Author: eduardomourar

packages/service-client-documentation-generator/package.json

@@ -31,8 +31,10 @@
     "concurrently": "7.0.0",
     "downlevel-dts": "0.10.1",
     "rimraf": "3.0.2",
-    "typedoc": "0.19.2",
-    "typescript": "~4.6.2"
+    "typescript": "4.7.3"
+  },
+  "typedoc": {
+    "entryPoint": "src/index.ts"
   },
   "typesVersions": {
     "<4.0": {

packages/service-client-documentation-generator/src/index.ts

@@ -1,25 +1,23 @@
-import { PluginHost } from "typedoc/dist/lib/utils";
+import { Application, ParameterType } from "typedoc";
 
-import { SdkClientCommentUpdatePlugin } from "./sdk-client-comment-update";
-import { SdkClientRemoveNavigatorPlugin } from "./sdk-client-remove-navigator";
 import { SdkClientRenameProjectPlugin } from "./sdk-client-rename-project";
 import { SdkClientTocPlugin } from "./sdk-client-toc-plugin";
 
-module.exports = function load(pluginHost: PluginHost) {
-  const application = pluginHost.owner;
+export function load(app: Application) {
+  app.options.addDeclaration({
+    name: "defaultServiceSuffix",
+    help: "Default suffix to be used when renaming service project.",
+    defaultValue: "AWS SDK for JavaScript v3",
+    type: ParameterType.String,
+  });
+  app.options.addDeclaration({
+    name: "defaultGroup",
+    help: "Default group to place categories as children",
+    defaultValue: "SDK",
+    type: ParameterType.String,
+  });
 
-  application.converter.addComponent(
-    "SdkClientCommentUpdatePlugin",
-    new SdkClientCommentUpdatePlugin(application.converter)
-  );
+  new SdkClientRenameProjectPlugin(app.options, app.logger, app.renderer);
 
-  application.renderer.addComponent("SdkClientTocPlugin", new SdkClientTocPlugin(application.renderer));
-  application.renderer.addComponent(
-    "SdkClientRenameProjectPlugin",
-    new SdkClientRenameProjectPlugin(application.renderer)
-  );
-  application.renderer.addComponent(
-    "SdkClientRemoveNavigatorPlugin",
-    new SdkClientRemoveNavigatorPlugin(application.renderer)
-  );
-};
+  new SdkClientTocPlugin(app.options, app.logger, app.renderer);
+}

packages/service-client-documentation-generator/src/sdk-client-comment-update.ts

@@ -1,35 +1,51 @@
 import { readFileSync } from "fs";
-import { Component, RendererComponent } from "typedoc/dist/lib/output/components";
-import { RendererEvent } from "typedoc/dist/lib/output/events";
+import path from "path";
+import { BindOption, Context, Converter, Logger, Options, Reflection, Renderer, RendererEvent } from "typedoc";
 
-import { getCurrentClientDirectory } from "./utils";
+import { isClientModel } from "./utils";
 
 /**
  * Correct the package name in the navigator.
  */
-@Component({ name: "SdkClientRenameProject" })
-export class SdkClientRenameProjectPlugin extends RendererComponent {
+export class SdkClientRenameProjectPlugin {
   private projectName: string | undefined = undefined;
-  initialize() {
-    this.listenTo(this.owner, {
-      [RendererEvent.BEGIN]: this.onRenderedBegin,
-    });
+
+  @BindOption("defaultServiceSuffix")
+  readonly defaultServiceSuffix: string;
+
+  constructor(public readonly options: Options, public readonly logger: Logger, private readonly renderer: Renderer) {
+    this.renderer.application.converter.on(Converter.EVENT_CREATE_DECLARATION, this.onCreateDeclaration);
+    this.renderer.on(Renderer.EVENT_BEGIN, this.onRendererBegin);
   }
 
-  onRenderedBegin(event: RendererEvent) {
+  /**
+   * Triggered when the converter creates the declaration of a project.
+   *
+   * @param context  The context object describing the current state the converter is in.
+   */
+  private onCreateDeclaration = (_context: Context, reflection: Reflection) => {
+    const defaultCommentTag = reflection.comment?.getTag("@default") || reflection.comment?.getTag("@defaultValue");
+    if (isClientModel(reflection) && reflection.name === "serviceId" && defaultCommentTag) {
+      const defaultValue = defaultCommentTag.content[0]?.text?.replace(/"/g, "");
+      if (defaultValue && !this.projectName) {
+        this.projectName = `${defaultValue} Client - ${this.defaultServiceSuffix}`;
+      }
+    }
+  };
+
+  /**
+   * Triggered when the renderer is starting.
+   *
+   * @param event  The project the renderer is currently processing.
+   */
+  private onRendererBegin = (event: RendererEvent) => {
     if (!this.projectName) {
-      const clientDirectory = getCurrentClientDirectory(event);
-      const metadataDir = clientDirectory.files.filter((sourceFile) =>
-        sourceFile.fileName.endsWith("/package.json")
-      )?.[0]?.fullFileName;
-      const { name } = metadataDir || JSON.parse(readFileSync(metadataDir).toString());
-      const serviceIdReflection = clientDirectory.directories.src.files
-        ?.filter((sourceFile) => sourceFile.fileName.endsWith("/runtimeConfig.shared.ts"))?.[0]
-        .reflections.filter((reflection) => reflection.name === "serviceId")?.[0];
-      this.projectName = serviceIdReflection /* serviceIdReflection.defaultValue looks like '"S3"' */
-        ? `${(serviceIdReflection as any).defaultValue.match(/"(.*)"/)[1]} Client - AWS SDK for JavaScript v3`
-        : name;
+      const children = Object.values(event.project.reflections).filter(isClientModel);
+      const clientDirectory = path.dirname(path.dirname(children[0].sources[0].fullFileName));
+      const metadataPath = path.join(clientDirectory, "package.json");
+      const { name } = JSON.parse(readFileSync(metadataPath).toString());
+      this.projectName = name;
     }
     event.project.name = this.projectName;
-  }
+  };
 }