Merge branch 'main' into fix-various-todos

Author: Shinigami92

scripts/apidoc.ts

@@ -3,6 +3,11 @@ import * as TypeDoc from 'typedoc';
 import { writeApiPagesIndex } from './apidoc/apiDocsWriter';
 import { processDirectMethods } from './apidoc/directMethods';
 import { processModuleMethods } from './apidoc/moduleMethods';
+import {
+  DefaultParameterAwareSerializer,
+  parameterDefaultReader,
+  patchProjectParameterDefaults,
+} from './apidoc/parameterDefaults';
 import type { PageIndex } from './apidoc/utils';
 import { pathOutputDir } from './apidoc/utils';
 
@@ -15,6 +20,14 @@ async function build(): Promise<void> {
   // If you want TypeDoc to load typedoc.json files
   //app.options.addReader(new TypeDoc.TypeDocReader());
 
+  // Read parameter defaults
+  app.converter.on(
+    TypeDoc.Converter.EVENT_CREATE_DECLARATION,
+    parameterDefaultReader
+  );
+  // Add to debug json output
+  app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined));
+
   app.bootstrap({
     entryPoints: ['src/index.ts'],
     pretty: true,
@@ -31,6 +44,8 @@ async function build(): Promise<void> {
   await app.generateJson(project, pathOutputJson);
   console.log(pathOutputDir);
 
+  patchProjectParameterDefaults(project);
+
   const modulesPages: PageIndex = [];
   modulesPages.push({ text: 'Localization', link: '/api/localization.html' });
   modulesPages.push(...processModuleMethods(project));

scripts/apidoc/parameterDefaults.ts

@@ -0,0 +1,130 @@
+import type {
+  Context,
+  DeclarationReflection,
+  EventCallback,
+  JSONOutput,
+  ProjectReflection,
+  SignatureReflection,
+} from 'typedoc';
+import {
+  Reflection,
+  ReflectionKind,
+  SerializerComponent,
+  TypeScript,
+} from 'typedoc';
+
+const reflectionKindFunctionOrMethod =
+  ReflectionKind.Function | ReflectionKind.Method;
+
+interface ParameterDefaultsAware extends Reflection {
+  implementationDefaultParameters: string[];
+}
+
+/**
+ * TypeDoc EventCallback for EVENT_CREATE_DECLARATION events that reads the default parameters from the implementation.
+ */
+export const parameterDefaultReader: EventCallback = (
+  context: Context,
+  reflection: Reflection
+): void => {
+  const symbol = context.project.getSymbolFromReflection(reflection);
+  if (!symbol) return;
+
+  if (
+    reflection.kindOf(reflectionKindFunctionOrMethod) &&
+    symbol.declarations?.length
+  ) {
+    const lastDeclaration = symbol.declarations[symbol.declarations.length - 1];
+    if (TypeScript.isFunctionLike(lastDeclaration)) {
+      (reflection as ParameterDefaultsAware).implementationDefaultParameters =
+        lastDeclaration.parameters.map((param) =>
+          cleanParameterDefault(param.initializer?.getText())
+        );
+    }
+  }
+};
+
+/**
+ * Removes compile expressions that don't add any value for readers.
+ *
+ * @param value The default value to clean.
+ * @returns The cleaned default value.
+ */
+function cleanParameterDefault(value?: string): string {
+  if (value == null) {
+    return undefined;
+  }
+  // Strip type casts: "'foobar' as unknown as T" => "'foobar'"
+  return value.replace(/ as unknown as [A-Za-z<>]+/, '');
+}
+
+/**
+ * Serializer that adds the `implementationDefaultParameters` to the JSON output.
+ */
+export class DefaultParameterAwareSerializer extends SerializerComponent<Reflection> {
+  serializeGroup(instance: unknown): boolean {
+    return instance instanceof Reflection;
+  }
+
+  supports(item: unknown): boolean {
+    return true;
+  }
+
+  toObject(item: Reflection, obj?: object): Partial<JSONOutput.Reflection> {
+    (obj as ParameterDefaultsAware).implementationDefaultParameters = (
+      item as ParameterDefaultsAware
+    ).implementationDefaultParameters;
+    return obj;
+  }
+}
+
+/**
+ * Replaces all methods' last signature's parameter's default value with the default value read from the implementation.
+ *
+ * @param project The project to patch.
+ */
+export function patchProjectParameterDefaults(
+  project: ProjectReflection
+): void {
+  const functionOrMethods = project.getReflectionsByKind(
+    reflectionKindFunctionOrMethod
+  ) as DeclarationReflection[];
+  for (const functionOrMethod of functionOrMethods) {
+    patchMethodParameterDefaults(functionOrMethod);
+  }
+}
+
+/**
+ * Replaces the last signature's parameter's default value with the default value read from the implementation.
+ *
+ * @param method The method to patch.
+ */
+function patchMethodParameterDefaults(method: DeclarationReflection): void {
+  const signatures = method.signatures;
+  const signature = signatures[signatures.length - 1];
+  const parameterDefaults = (method as unknown as ParameterDefaultsAware)
+    .implementationDefaultParameters;
+  if (parameterDefaults) {
+    patchSignatureParameterDefaults(signature, parameterDefaults);
+  }
+}
+
+/**
+ * Replaces the given signature's parameter's default value with the given default values.
+ *
+ * @param signature The signature to patch.
+ * @param parameterDefaults The defaults to add.
+ */
+function patchSignatureParameterDefaults(
+  signature: SignatureReflection,
+  parameterDefaults: string[]
+): void {
+  const signatureParameters = signature.parameters;
+  if (signatureParameters.length !== parameterDefaults.length) {
+    throw new Error('Unexpected parameter length mismatch');
+  }
+  signatureParameters.forEach(
+    (param, index) =>
+      (param.defaultValue = parameterDefaults[index] || param.defaultValue)
+  );
+}

scripts/apidoc/signature.ts

@@ -162,7 +162,8 @@ function analyzeParameter(parameter: ParameterReflection): {
   const name = parameter.name;
   const declarationName = name + (isOptional(parameter) ? '?' : '');
   const type = parameter.type;
-  const defaultValue = parameter.defaultValue;
+  const commentDefault = extractDefaultFromComment(parameter.comment);
+  const defaultValue = parameter.defaultValue ?? commentDefault;
 
   let signatureText = '';
   if (defaultValue) {
@@ -200,6 +201,7 @@ function analyzeParameterOptions(
     return properties.map((property) => ({
       name: `${name}.${property.name}${isOptional(property) ? '?' : ''}`,
       type: declarationTypeToText(property),
+      default: extractDefaultFromComment(property.comment),
       description: mdToHtml(
         toBlock(property.comment ?? property.signatures?.[0].comment)
       ),
@@ -284,3 +286,25 @@ function signatureTypeToText(signature: SignatureReflection): string {
     .map((p) => `${p.name}: ${typeToText(p.type)}`)
     .join(', ')}) => ${typeToText(signature.type)}`;
 }
+
+/**
+ * Extracts and removed the parameter default from the comments.
+ *
+ * @param comment The comment to extract the default from.
+ * @returns The extracted default value.
+ */
+function extractDefaultFromComment(comment?: Comment): string {
+  if (!comment) {
+    return;
+  }
+  const text = comment.shortText;
+  if (!text || text.trim() === '') {
+    return;
+  }
+  const result = /(.*)[ \n]Defaults to `([^`]+)`./.exec(text);
+  if (!result) {
+    return;
+  }
+  comment.shortText = result[1];
+  return result[2];
+}