Fixed JSDoc comments and optional params parsing

src/lib/converter/factories/comment.ts

@@ -238,6 +238,10 @@ export function parseComment(
             if (param) {
                 paramName = param[0];
                 line = line.substr(paramName.length + 1).trim();
+                // "[optionalArg]" -> "optionalArg"
+                if (/^\[.*\]$/.test(paramName)) {
+                    paramName = paramName.slice(1, -1);
+                }
             }
             line = consumeTypeData(line);
             line = line.replace(/^-\s+/, "");

src/lib/converter/factories/signature.ts

@@ -1,6 +1,7 @@
 import * as ts from "typescript";
 import * as assert from "assert";
 import {
+    Comment,
     DeclarationReflection,
     IntrinsicType,
     ParameterReflection,
@@ -15,6 +16,7 @@ import type { Context } from "../context";
 import { ConverterEvents } from "../converter-events";
 import { convertDefaultValue } from "../convert-expression";
 import { removeUndefined } from "../utils/reflections";
+import { getJsDocCommentText } from "./comment";
 
 export function createSignature(
     context: Context,
@@ -146,9 +148,15 @@ function convertParameters(
 
         let isOptional = false;
         if (declaration) {
-            isOptional = ts.isParameter(declaration)
-                ? !!declaration.questionToken
-                : declaration.isBracketed;
+            if (ts.isParameter(declaration)) {
+                const paramTag = ts
+                    .getJSDocTags(declaration)
+                    .find(ts.isJSDocParameterTag);
+                isOptional =
+                    !!declaration.questionToken || !!paramTag?.isBracketed;
+            } else {
+                isOptional = declaration.isBracketed;
+            }
         }
 
         if (isOptional) {
@@ -212,6 +220,13 @@ export function convertParameterNodes(
                 : !!param.typeExpression &&
                       ts.isJSDocVariadicType(param.typeExpression.type)
         );
+
+        if (ts.isJSDocParameterTag(param)) {
+            const comment = getJsDocCommentText(param.comment);
+            if (comment) {
+                paramRefl.comment = new Comment(comment);
+            }
+        }
         return paramRefl;
     });
 }

src/test/converter/js/specs.json

@@ -491,6 +491,9 @@
                       "flags": {
                         "isOptional": true
                       },
+                      "comment": {
+                        "shortText": "an optional argument"
+                      },
                       "type": {
                         "type": "intrinsic",
                         "name": "string"

src/test/converter2/issues/gh1804.js

@@ -0,0 +1,4 @@
+/**
+ * @param {number} [arg]
+ */
+export function foo(arg) {}

src/test/converter2/issues/gh567.js

@@ -0,0 +1,9 @@
+/**
+ * @param {number} [arg1] another optional argument
+ */
+function someFunc(arg1) {}
+
+/**
+ * @callback SomeCallback
+ * @param {string} [arg0] an optional argument
+ */

src/test/issueTests.ts

@@ -19,6 +19,22 @@ function query(project: ProjectReflection, name: string) {
 export const issueTests: {
     [issue: string]: (project: ProjectReflection) => void;
 } = {
+    gh567(project) {
+        const callback = query(project, "SomeCallback");
+        ok(callback.type instanceof ReflectionType);
+        equal(
+            callback.type.declaration.signatures?.[0].parameters?.[0].comment
+                ?.shortText,
+            "an optional argument"
+        );
+
+        const func = query(project, "someFunc");
+        equal(
+            func?.signatures?.[0].parameters?.[0].comment?.shortText,
+            "another optional argument\n"
+        );
+    },
+
     gh869(project) {
         const classFoo = project.children?.find(
             (r) => r.name === "Foo" && r.kind === ReflectionKind.Class
@@ -290,4 +306,10 @@ export const issueTests: {
         ok(project.children![0].kind === ReflectionKind.Reference);
         ok(project.children![1].kind !== ReflectionKind.Reference);
     },
+
+    gh1804(project) {
+        const foo = query(project, "foo");
+        ok(foo?.signatures?.[0].parameters?.[0].flags.isOptional);
+        equal(foo?.signatures?.[0].parameters?.[0].type?.toString(), "number");
+    },
 };