From 332b5bcfd6752d7cce07968f4429a1a1c5c67943 Mon Sep 17 00:00:00 2001
From: 3bl3gamer <3bl3gamer@gmail.com>
Date: Sat, 27 Nov 2021 15:58:44 +0300
Subject: [PATCH] Fixed JSDoc comments and optional params parsing

---
 src/lib/converter/factories/comment.ts   |  4 ++++
 src/lib/converter/factories/signature.ts | 21 ++++++++++++++++++---
 src/test/converter/js/specs.json         |  3 +++
 src/test/converter2/issues/gh1804.js     |  4 ++++
 src/test/converter2/issues/gh567.js      |  9 +++++++++
 src/test/issueTests.ts                   | 22 ++++++++++++++++++++++
 6 files changed, 60 insertions(+), 3 deletions(-)
 create mode 100644 src/test/converter2/issues/gh1804.js
 create mode 100644 src/test/converter2/issues/gh567.js

diff --git a/src/lib/converter/factories/comment.ts b/src/lib/converter/factories/comment.ts
index e832ad55f..1da042017 100644
--- a/src/lib/converter/factories/comment.ts
+++ b/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+/, "");
diff --git a/src/lib/converter/factories/signature.ts b/src/lib/converter/factories/signature.ts
index e3768bf71..b5935173f 100644
--- a/src/lib/converter/factories/signature.ts
+++ b/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;
     });
 }
diff --git a/src/test/converter/js/specs.json b/src/test/converter/js/specs.json
index d3a44cdc0..c6d941bd9 100644
--- a/src/test/converter/js/specs.json
+++ b/src/test/converter/js/specs.json
@@ -491,6 +491,9 @@
                       "flags": {
                         "isOptional": true
                       },
+                      "comment": {
+                        "shortText": "an optional argument"
+                      },
                       "type": {
                         "type": "intrinsic",
                         "name": "string"
diff --git a/src/test/converter2/issues/gh1804.js b/src/test/converter2/issues/gh1804.js
new file mode 100644
index 000000000..35dedaad3
--- /dev/null
+++ b/src/test/converter2/issues/gh1804.js
@@ -0,0 +1,4 @@
+/**
+ * @param {number} [arg]
+ */
+export function foo(arg) {}
diff --git a/src/test/converter2/issues/gh567.js b/src/test/converter2/issues/gh567.js
new file mode 100644
index 000000000..6b50315d0
--- /dev/null
+++ b/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
+ */
diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts
index e6257070b..07fc40e78 100644
--- a/src/test/issueTests.ts
+++ b/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");
+    },
 };