docs: document options params in api docs

faker-js · Mar 1, 2022 · a741d1f · a741d1f
1 parent a17209c
commit a741d1f
Showing 1 changed file with 67 additions and 25 deletions.
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
@@ -1,5 +1,5 @@
 import sanitizeHtml from 'sanitize-html';
-import type * as TypeDoc from 'typedoc';
+import * as TypeDoc from 'typedoc';
 import { createMarkdownRenderer } from 'vitepress';
 import type {
   Method,
@@ -78,36 +78,16 @@ export function analyzeSignature(
 
   // Collect Parameters
   const signatureParameters: string[] = [];
-  let requiresArgs = false;
   for (
     let index = 0;
     signature.parameters && index < signature.parameters.length;
     index++
   ) {
     const parameter = signature.parameters[index];
 
-    const parameterDefault = parameter.defaultValue;
-    const parameterRequired = typeof parameterDefault === 'undefined';
-    if (index === 0) {
-      requiresArgs = parameterRequired;
-    }
-    const parameterName = parameter.name + (parameterRequired ? '?' : '');
-    const parameterType = parameter.type.toString();
-
-    let parameterDefaultSignatureText = '';
-    if (!parameterRequired) {
-      parameterDefaultSignatureText = ' = ' + parameterDefault;
-    }
-
-    signatureParameters.push(
-      parameterName + ': ' + parameterType + parameterDefaultSignatureText
-    );
-    parameters.push({
-      name: parameter.name,
-      type: parameterType,
-      default: parameterDefault,
-      description: mdToHtml(toBlock(parameter.comment)),
-    });
+    const aParam = analyzeParameter(parameter);
+    signatureParameters.push(aParam.signature);
+    parameters.push(...aParam.parameters);
   }
 
   // Generate usage section
@@ -125,7 +105,7 @@ export function analyzeSignature(
     examples = `faker.${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type.toString()}\n`;
   }
   faker.seed(0);
-  if (!requiresArgs && moduleName) {
+  if (moduleName) {
     try {
       let example = JSON.stringify(faker[moduleName][methodName]());
       if (example.length > 50) {
@@ -164,3 +144,65 @@ export function analyzeSignature(
     seeAlsos,
   };
 }
+
+function analyzeParameter(parameter: TypeDoc.ParameterReflection): {
+  parameters: MethodParameter[];
+  signature: string;
+} {
+  const name = parameter.name;
+  const declarationName = name + (isOptional(parameter) ? '?' : '');
+  const type = parameter.type;
+  const typeText = type.toString();
+  const defaultValue = parameter.defaultValue;
+
+  let signatureText = '';
+  if (defaultValue) {
+    signatureText = ' = ' + defaultValue;
+  }
+
+  const signature = declarationName + ': ' + typeText + signatureText;
+
+  const parameters: MethodParameter[] = [
+    {
+      name: declarationName,
+      type: typeText,
+      default: defaultValue,
+      description: mdToHtml(toBlock(parameter.comment)),
+    },
+  ];
+  parameters.push(...analyzeParameterOptions(name, type));
+
+  return {
+    parameters,
+    signature,
+  };
+}
+
+function analyzeParameterOptions(
+  name: string,
+  parameterType: TypeDoc.SomeType
+): MethodParameter[] {
+  if (parameterType.type === 'union') {
+    return [];
+    // TODO ST-DDT 2022-02-26: Currently not supported by typedoc
+    // https://github.com/TypeStrong/typedoc/issues/1876
+    // return parameterType.types.flatMap((type) =>
+    //   analyzeParameterOptions(name, type)
+    // );
+  } else if (parameterType.type === 'reflection') {
+    const properties = parameterType.declaration.getChildrenByKind(
+      TypeDoc.ReflectionKind.Property
+    );
+    return properties.map((property) => ({
+      name: `${name}.${property.name}${isOptional(property) ? '?' : ''}`,
+      type: property.type.toString(),
+      description: mdToHtml(toBlock(property.comment)),
+    }));
+  }
+
+  return [];
+}
+
+function isOptional(parameter: TypeDoc.Reflection): boolean {
+  return parameter.flags.hasFlag(TypeDoc.ReflectionFlag.Optional);
+}