docs: extract defaults from the comments if absent otherwise (#657)

Co-authored-by: Daniel Bannert <[email protected]>

1 files changed, 25 insertions, 1 deletions

diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index bfeb01e6..926b5a7c 100644
--- a/scripts/apidoc/signature.ts
+++ b/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];
+}