From c4334a2197338384c7eece9d12f6c93ccc280711 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Fri, 6 May 2022 22:11:39 -0400
Subject: [PATCH 01/13] todo

---
 test/unit/comments.spec.ts | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 test/unit/comments.spec.ts

diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
new file mode 100644
index 000000000..115789d29
--- /dev/null
+++ b/test/unit/comments.spec.ts
@@ -0,0 +1,19 @@
+import * as util from "../util";
+
+test("JSDoc is copied", () => {
+    const builder = util.testModule`
+        /**
+         * LOL
+         */
+        function foo() {}
+        // POOP
+    `
+        .expectToHaveNoDiagnostics();
+
+    const transpiledFile = builder.getLuaResult().transpiledFiles[0];
+    util.assert(transpiledFile !== undefined);
+    const { lua } =  transpiledFile;
+    util.assert(lua !== undefined);
+    console.log(lua);
+    expect(lua).toContain("LOL");
+});

From acbe98fcc55886366b0b33cc05f28b8ba59b1f8e Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 7 May 2022 00:42:11 -0400
Subject: [PATCH 02/13] comment feature works

---
 src/transformation/utils/lua-ast.ts | 60 +++++++++++++++++++++++++++++
 test/unit/comments.spec.ts          | 26 +++++++++++--
 2 files changed, 82 insertions(+), 4 deletions(-)

diff --git a/src/transformation/utils/lua-ast.ts b/src/transformation/utils/lua-ast.ts
index b894dba63..229fdace2 100644
--- a/src/transformation/utils/lua-ast.ts
+++ b/src/transformation/utils/lua-ast.ts
@@ -202,6 +202,8 @@ export function createLocalOrExportedOrGlobalDeclaration(
         }
     }
 
+    applyJSDocComments(context, tsOriginal, declaration, assignment);
+
     if (declaration && assignment) {
         return [declaration, assignment];
     } else if (declaration) {
@@ -213,6 +215,64 @@ export function createLocalOrExportedOrGlobalDeclaration(
     }
 }
 
+/**
+ * Apply JSDoc comments to the newly-created Lua statement, if present.
+ * https://stackoverflow.com/questions/47429792/is-it-possible-to-get-comments-as-nodes-in-the-ast-using-the-typescript-compiler
+ */
+function applyJSDocComments(
+    context: TransformationContext,
+    tsOriginal: ts.Node | undefined,
+    declaration: lua.VariableDeclarationStatement | undefined,
+    assignment: lua.AssignmentStatement | undefined
+) {
+    const docComment = extractJSDocCommentFromTSNode(context, tsOriginal);
+    if (docComment === undefined) {
+        return;
+    }
+
+    // By default, TSTL will display comments immediately next to the "--" characters. We can make
+    // the comments look better if we separate them by a space (similar to what Prettier does in
+    // JavaScript/TypeScript).
+    const docCommentWithSpace = docComment.map((line) => ` ${line}`);
+
+    if (declaration && assignment) {
+        declaration.leadingComments = docCommentWithSpace;
+    } else if (declaration) {
+        declaration.leadingComments = docCommentWithSpace;
+    } else if (assignment) {
+        assignment.leadingComments = docCommentWithSpace;
+    }
+}
+
+function extractJSDocCommentFromTSNode(
+    context: TransformationContext,
+    tsOriginal: ts.Node | undefined,
+) {
+    if (tsOriginal === undefined) {
+        return undefined;
+    }
+
+    // The "name" property is only on a subset of node types; we want to be permissive and get the
+    // comments from as many nodes as possible.
+    const node = tsOriginal as any;
+    if (node.name === undefined) {
+        return undefined;
+    }
+
+    const symbol = context.checker.getSymbolAtLocation(node.name);
+    if (symbol === undefined) {
+        return undefined;
+    }
+
+    const docCommentArray = symbol.getDocumentationComment(context.checker);
+    const docComment = ts.displayPartsToString(docCommentArray).trim();
+    if (docComment === "") {
+        return undefined;
+    }
+
+    return docComment.split("\n");
+}
+
 export const createNaN = (tsOriginal?: ts.Node) =>
     lua.createBinaryExpression(
         lua.createNumericLiteral(0),
diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
index 115789d29..0da90303e 100644
--- a/test/unit/comments.spec.ts
+++ b/test/unit/comments.spec.ts
@@ -1,12 +1,12 @@
 import * as util from "../util";
 
-test("JSDoc is copied", () => {
+test("JSDoc is copied on a function", () => {
     const builder = util.testModule`
         /**
-         * LOL
+         * This is a function comment.
+         * It has multiple lines.
          */
         function foo() {}
-        // POOP
     `
         .expectToHaveNoDiagnostics();
 
@@ -15,5 +15,23 @@ test("JSDoc is copied", () => {
     const { lua } =  transpiledFile;
     util.assert(lua !== undefined);
     console.log(lua);
-    expect(lua).toContain("LOL");
+    expect(lua).toContain("This is a function comment.");
+});
+
+test("JSDoc is copied on a variable", () => {
+    const builder = util.testModule`
+        /**
+         * This is a variable comment.
+         * It has multiple lines.
+         */
+        const foo = 123;
+    `
+        .expectToHaveNoDiagnostics();
+
+    const transpiledFile = builder.getLuaResult().transpiledFiles[0];
+    util.assert(transpiledFile !== undefined);
+    const { lua } =  transpiledFile;
+    util.assert(lua !== undefined);
+    console.log(lua);
+    expect(lua).toContain("This is a variable comment.");
 });

From f1cf9d5a21c88373235c5dd8e0d3e5a0c2cf47b6 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 7 May 2022 00:46:51 -0400
Subject: [PATCH 03/13] cleanup

---
 test/unit/comments.spec.ts | 2 --
 1 file changed, 2 deletions(-)

diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
index 0da90303e..037711aa9 100644
--- a/test/unit/comments.spec.ts
+++ b/test/unit/comments.spec.ts
@@ -14,7 +14,6 @@ test("JSDoc is copied on a function", () => {
     util.assert(transpiledFile !== undefined);
     const { lua } =  transpiledFile;
     util.assert(lua !== undefined);
-    console.log(lua);
     expect(lua).toContain("This is a function comment.");
 });
 
@@ -32,6 +31,5 @@ test("JSDoc is copied on a variable", () => {
     util.assert(transpiledFile !== undefined);
     const { lua } =  transpiledFile;
     util.assert(lua !== undefined);
-    console.log(lua);
     expect(lua).toContain("This is a variable comment.");
 });

From 6ca8227ea34ae5343165f975ba9e45debb7106cc Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Tue, 24 May 2022 01:25:28 -0400
Subject: [PATCH 04/13] fix: prettier

---
 src/transformation/utils/lua-ast.ts |  7 ++-----
 test/unit/comments.spec.ts          | 10 ++++------
 2 files changed, 6 insertions(+), 11 deletions(-)

diff --git a/src/transformation/utils/lua-ast.ts b/src/transformation/utils/lua-ast.ts
index 229fdace2..62753f9f6 100644
--- a/src/transformation/utils/lua-ast.ts
+++ b/src/transformation/utils/lua-ast.ts
@@ -233,7 +233,7 @@ function applyJSDocComments(
     // By default, TSTL will display comments immediately next to the "--" characters. We can make
     // the comments look better if we separate them by a space (similar to what Prettier does in
     // JavaScript/TypeScript).
-    const docCommentWithSpace = docComment.map((line) => ` ${line}`);
+    const docCommentWithSpace = docComment.map(line => ` ${line}`);
 
     if (declaration && assignment) {
         declaration.leadingComments = docCommentWithSpace;
@@ -244,10 +244,7 @@ function applyJSDocComments(
     }
 }
 
-function extractJSDocCommentFromTSNode(
-    context: TransformationContext,
-    tsOriginal: ts.Node | undefined,
-) {
+function extractJSDocCommentFromTSNode(context: TransformationContext, tsOriginal: ts.Node | undefined) {
     if (tsOriginal === undefined) {
         return undefined;
     }
diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
index 037711aa9..bc84bb61d 100644
--- a/test/unit/comments.spec.ts
+++ b/test/unit/comments.spec.ts
@@ -7,12 +7,11 @@ test("JSDoc is copied on a function", () => {
          * It has multiple lines.
          */
         function foo() {}
-    `
-        .expectToHaveNoDiagnostics();
+    `.expectToHaveNoDiagnostics();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
     util.assert(transpiledFile !== undefined);
-    const { lua } =  transpiledFile;
+    const { lua } = transpiledFile;
     util.assert(lua !== undefined);
     expect(lua).toContain("This is a function comment.");
 });
@@ -24,12 +23,11 @@ test("JSDoc is copied on a variable", () => {
          * It has multiple lines.
          */
         const foo = 123;
-    `
-        .expectToHaveNoDiagnostics();
+    `.expectToHaveNoDiagnostics();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
     util.assert(transpiledFile !== undefined);
-    const { lua } =  transpiledFile;
+    const { lua } = transpiledFile;
     util.assert(lua !== undefined);
     expect(lua).toContain("This is a variable comment.");
 });

From 3b8680e86b508c2fc97dceba4bc232bb6a12ac80 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 28 May 2022 10:01:17 -0400
Subject: [PATCH 05/13] fix for tests

---
 test/unit/comments.spec.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
index bc84bb61d..2c0c1e3ad 100644
--- a/test/unit/comments.spec.ts
+++ b/test/unit/comments.spec.ts
@@ -10,9 +10,9 @@ test("JSDoc is copied on a function", () => {
     `.expectToHaveNoDiagnostics();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
-    util.assert(transpiledFile !== undefined);
+    expect(transpiledFile).toBeDefined();
     const { lua } = transpiledFile;
-    util.assert(lua !== undefined);
+    expect(lua).toBeDefined();
     expect(lua).toContain("This is a function comment.");
 });
 
@@ -26,8 +26,8 @@ test("JSDoc is copied on a variable", () => {
     `.expectToHaveNoDiagnostics();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
-    util.assert(transpiledFile !== undefined);
+    expect(transpiledFile).toBeDefined();
     const { lua } = transpiledFile;
-    util.assert(lua !== undefined);
+    expect(lua).toBeDefined();
     expect(lua).toContain("This is a variable comment.");
 });

From d3d727782ac2117e863578fba47f85526e7509c4 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 28 May 2022 10:08:04 -0400
Subject: [PATCH 06/13] rename function

---
 src/transformation/utils/lua-ast.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/transformation/utils/lua-ast.ts b/src/transformation/utils/lua-ast.ts
index 62753f9f6..f260117a9 100644
--- a/src/transformation/utils/lua-ast.ts
+++ b/src/transformation/utils/lua-ast.ts
@@ -225,7 +225,7 @@ function applyJSDocComments(
     declaration: lua.VariableDeclarationStatement | undefined,
     assignment: lua.AssignmentStatement | undefined
 ) {
-    const docComment = extractJSDocCommentFromTSNode(context, tsOriginal);
+    const docComment = getJSDocCommentFromTSNode(context, tsOriginal);
     if (docComment === undefined) {
         return;
     }
@@ -244,7 +244,7 @@ function applyJSDocComments(
     }
 }
 
-function extractJSDocCommentFromTSNode(context: TransformationContext, tsOriginal: ts.Node | undefined) {
+function getJSDocCommentFromTSNode(context: TransformationContext, tsOriginal: ts.Node | undefined) {
     if (tsOriginal === undefined) {
         return undefined;
     }

From f3b9c6c6f08fc4eb5a2614fa37371f7db7baf6c9 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 28 May 2022 12:35:57 -0400
Subject: [PATCH 07/13] fix for removeComments config value

---
 src/transformation/utils/lua-ast.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/transformation/utils/lua-ast.ts b/src/transformation/utils/lua-ast.ts
index f260117a9..5f637218f 100644
--- a/src/transformation/utils/lua-ast.ts
+++ b/src/transformation/utils/lua-ast.ts
@@ -225,6 +225,10 @@ function applyJSDocComments(
     declaration: lua.VariableDeclarationStatement | undefined,
     assignment: lua.AssignmentStatement | undefined
 ) {
+    if (context.options.removeComments) {
+        return;
+    }
+
     const docComment = getJSDocCommentFromTSNode(context, tsOriginal);
     if (docComment === undefined) {
         return;

From 236e5af681b9788e3924f85d6eda721a18a1b534 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 28 May 2022 12:37:30 -0400
Subject: [PATCH 08/13] adding comment

---
 src/transformation/utils/lua-ast.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/transformation/utils/lua-ast.ts b/src/transformation/utils/lua-ast.ts
index 5f637218f..dd99f5b11 100644
--- a/src/transformation/utils/lua-ast.ts
+++ b/src/transformation/utils/lua-ast.ts
@@ -225,6 +225,8 @@ function applyJSDocComments(
     declaration: lua.VariableDeclarationStatement | undefined,
     assignment: lua.AssignmentStatement | undefined
 ) {
+    // Respect the vanilla TypeScript option of "removeComments":
+    // https://www.typescriptlang.org/tsconfig#removeComments
     if (context.options.removeComments) {
         return;
     }

From abd51f6fea1c55244e37ab209c48763a4d89140a Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 28 May 2022 19:48:54 -0400
Subject: [PATCH 09/13] adding snapshots

---
 test/unit/__snapshots__/comments.spec.ts.snap | 18 ++++++++++++++++++
 test/unit/comments.spec.ts                    |  4 ++--
 2 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100644 test/unit/__snapshots__/comments.spec.ts.snap

diff --git a/test/unit/__snapshots__/comments.spec.ts.snap b/test/unit/__snapshots__/comments.spec.ts.snap
new file mode 100644
index 000000000..c6b530f8a
--- /dev/null
+++ b/test/unit/__snapshots__/comments.spec.ts.snap
@@ -0,0 +1,18 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`JSDoc is copied on a function: code 1`] = `
+"-- This is a function comment.
+-- It has multiple lines.
+function foo(self)
+end"
+`;
+
+exports[`JSDoc is copied on a function: diagnostics 1`] = `""`;
+
+exports[`JSDoc is copied on a variable: code 1`] = `
+"-- This is a variable comment.
+-- It has multiple lines.
+foo = 123"
+`;
+
+exports[`JSDoc is copied on a variable: diagnostics 1`] = `""`;
diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
index 2c0c1e3ad..ac3a02ea1 100644
--- a/test/unit/comments.spec.ts
+++ b/test/unit/comments.spec.ts
@@ -7,7 +7,7 @@ test("JSDoc is copied on a function", () => {
          * It has multiple lines.
          */
         function foo() {}
-    `.expectToHaveNoDiagnostics();
+    `.expectToHaveNoDiagnostics().expectDiagnosticsToMatchSnapshot();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
     expect(transpiledFile).toBeDefined();
@@ -23,7 +23,7 @@ test("JSDoc is copied on a variable", () => {
          * It has multiple lines.
          */
         const foo = 123;
-    `.expectToHaveNoDiagnostics();
+    `.expectToHaveNoDiagnostics().expectDiagnosticsToMatchSnapshot();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
     expect(transpiledFile).toBeDefined();

From b219e7097fa361ac035a539668c3399529548b9c Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sat, 28 May 2022 20:03:57 -0400
Subject: [PATCH 10/13] fix prettier

---
 test/unit/comments.spec.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
index ac3a02ea1..077d711f3 100644
--- a/test/unit/comments.spec.ts
+++ b/test/unit/comments.spec.ts
@@ -7,7 +7,9 @@ test("JSDoc is copied on a function", () => {
          * It has multiple lines.
          */
         function foo() {}
-    `.expectToHaveNoDiagnostics().expectDiagnosticsToMatchSnapshot();
+    `
+        .expectToHaveNoDiagnostics()
+        .expectDiagnosticsToMatchSnapshot();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
     expect(transpiledFile).toBeDefined();
@@ -23,7 +25,9 @@ test("JSDoc is copied on a variable", () => {
          * It has multiple lines.
          */
         const foo = 123;
-    `.expectToHaveNoDiagnostics().expectDiagnosticsToMatchSnapshot();
+    `
+        .expectToHaveNoDiagnostics()
+        .expectDiagnosticsToMatchSnapshot();
 
     const transpiledFile = builder.getLuaResult().transpiledFiles[0];
     expect(transpiledFile).toBeDefined();

From 1cfaa084ef5c64e3a3fecf49d3c3dd8d880b2977 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sun, 29 May 2022 16:49:17 -0400
Subject: [PATCH 11/13] feat: jsdoc tag detection

---
 src/transformation/utils/lua-ast.ts           | 68 ++++++++++++++-----
 test/unit/__snapshots__/comments.spec.ts.snap | 44 ++++++++++--
 test/unit/comments.spec.ts                    | 68 +++++++++++++++++--
 3 files changed, 153 insertions(+), 27 deletions(-)

diff --git a/src/transformation/utils/lua-ast.ts b/src/transformation/utils/lua-ast.ts
index dd99f5b11..969ba75a8 100644
--- a/src/transformation/utils/lua-ast.ts
+++ b/src/transformation/utils/lua-ast.ts
@@ -202,7 +202,7 @@ export function createLocalOrExportedOrGlobalDeclaration(
         }
     }
 
-    applyJSDocComments(context, tsOriginal, declaration, assignment);
+    setJSDocComments(context, tsOriginal, declaration, assignment);
 
     if (declaration && assignment) {
         return [declaration, assignment];
@@ -219,7 +219,7 @@ export function createLocalOrExportedOrGlobalDeclaration(
  * Apply JSDoc comments to the newly-created Lua statement, if present.
  * https://stackoverflow.com/questions/47429792/is-it-possible-to-get-comments-as-nodes-in-the-ast-using-the-typescript-compiler
  */
-function applyJSDocComments(
+function setJSDocComments(
     context: TransformationContext,
     tsOriginal: ts.Node | undefined,
     declaration: lua.VariableDeclarationStatement | undefined,
@@ -231,26 +231,24 @@ function applyJSDocComments(
         return;
     }
 
-    const docComment = getJSDocCommentFromTSNode(context, tsOriginal);
-    if (docComment === undefined) {
+    const docCommentArray = getJSDocCommentFromTSNode(context, tsOriginal);
+    if (docCommentArray === undefined) {
         return;
     }
 
-    // By default, TSTL will display comments immediately next to the "--" characters. We can make
-    // the comments look better if we separate them by a space (similar to what Prettier does in
-    // JavaScript/TypeScript).
-    const docCommentWithSpace = docComment.map(line => ` ${line}`);
-
     if (declaration && assignment) {
-        declaration.leadingComments = docCommentWithSpace;
+        declaration.leadingComments = docCommentArray;
     } else if (declaration) {
-        declaration.leadingComments = docCommentWithSpace;
+        declaration.leadingComments = docCommentArray;
     } else if (assignment) {
-        assignment.leadingComments = docCommentWithSpace;
+        assignment.leadingComments = docCommentArray;
     }
 }
 
-function getJSDocCommentFromTSNode(context: TransformationContext, tsOriginal: ts.Node | undefined) {
+function getJSDocCommentFromTSNode(
+    context: TransformationContext,
+    tsOriginal: ts.Node | undefined
+): string[] | undefined {
     if (tsOriginal === undefined) {
         return undefined;
     }
@@ -267,13 +265,51 @@ function getJSDocCommentFromTSNode(context: TransformationContext, tsOriginal: t
         return undefined;
     }
 
+    // The TypeScript compiler separates JSDoc comments into the "documentation comment" and the
+    // "tags". The former is conventionally at the top of the comment, and the bottom is
+    // conventionally at the bottom. We need to get both from the TypeScript API and then combine
+    // them into one block of text.
     const docCommentArray = symbol.getDocumentationComment(context.checker);
-    const docComment = ts.displayPartsToString(docCommentArray).trim();
-    if (docComment === "") {
+    const docCommentText = ts.displayPartsToString(docCommentArray).trim();
+
+    const jsDocTagInfoArray = symbol.getJsDocTags(context.checker);
+    const jsDocTagsTextLines = jsDocTagInfoArray.map(jsDocTagInfo => {
+        let text = "@" + jsDocTagInfo.name;
+        if (jsDocTagInfo.text !== undefined) {
+            const tagDescriptionTextArray = jsDocTagInfo.text
+                .filter(symbolDisplayPart => symbolDisplayPart.text.trim() !== "")
+                .map(symbolDisplayPart => symbolDisplayPart.text.trim());
+            const tagDescriptionText = tagDescriptionTextArray.join(" ");
+            text += " " + tagDescriptionText;
+        }
+        return text;
+    });
+    const jsDocTagsText = jsDocTagsTextLines.join("\n");
+
+    const combined = (docCommentText + "\n\n" + jsDocTagsText).trim();
+    if (combined === "") {
         return undefined;
     }
 
-    return docComment.split("\n");
+    // By default, TSTL will display comments immediately next to the "--" characters. We can make
+    // the comments look better if we separate them by a space (similar to what Prettier does in
+    // JavaScript/TypeScript).
+    const linesWithoutSpace = combined.split("\n");
+    const lines = linesWithoutSpace.map(line => ` ${line}`);
+
+    // We want to JSDoc comments to map on to LDoc comments:
+    // https://stevedonovan.github.io/ldoc/manual/doc.md.html
+    // LDoc comments require that the first line starts with three hyphens.
+    // Thus, need to add one or more hyphens to the first line.
+    const firstLine = lines[0];
+    if (firstLine.startsWith(" @")) {
+        lines.unshift("-");
+    } else {
+        lines.shift();
+        lines.unshift("-" + firstLine);
+    }
+
+    return lines;
 }
 
 export const createNaN = (tsOriginal?: ts.Node) =>
diff --git a/test/unit/__snapshots__/comments.spec.ts.snap b/test/unit/__snapshots__/comments.spec.ts.snap
index c6b530f8a..23b89dcb7 100644
--- a/test/unit/__snapshots__/comments.spec.ts.snap
+++ b/test/unit/__snapshots__/comments.spec.ts.snap
@@ -1,18 +1,50 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`JSDoc is copied on a function: code 1`] = `
-"-- This is a function comment.
+exports[`JSDoc is copied on a function with tags: code 1`] = `
+"--- This is a function comment.
 -- It has multiple lines.
-function foo(self)
+-- 
+-- @param arg1 This is the first argument.
+-- @param arg2 This is the second argument.
+-- @returns A very powerful string.
+function foo(self, arg1, arg2)
+    return \\"bar\\"
 end"
 `;
 
-exports[`JSDoc is copied on a function: diagnostics 1`] = `""`;
+exports[`JSDoc is copied on a function with tags: diagnostics 1`] = `""`;
 
 exports[`JSDoc is copied on a variable: code 1`] = `
-"-- This is a variable comment.
--- It has multiple lines.
+"--- This is a variable comment.
 foo = 123"
 `;
 
 exports[`JSDoc is copied on a variable: diagnostics 1`] = `""`;
+
+exports[`Multi-line JSDoc with one block is copied on a function: code 1`] = `
+"--- This is a function comment.
+-- It has more than one line.
+function foo(self)
+end"
+`;
+
+exports[`Multi-line JSDoc with one block is copied on a function: diagnostics 1`] = `""`;
+
+exports[`Multi-line JSDoc with two blocks is copied on a function: code 1`] = `
+"--- This is a function comment.
+-- It has more than one line.
+-- 
+-- It also has more than one block.
+function foo(self)
+end"
+`;
+
+exports[`Multi-line JSDoc with two blocks is copied on a function: diagnostics 1`] = `""`;
+
+exports[`Single-line JSDoc is copied on a function: code 1`] = `
+"--- This is a function comment.
+function foo(self)
+end"
+`;
+
+exports[`Single-line JSDoc is copied on a function: diagnostics 1`] = `""`;
diff --git a/test/unit/comments.spec.ts b/test/unit/comments.spec.ts
index 077d711f3..58e648ad3 100644
--- a/test/unit/comments.spec.ts
+++ b/test/unit/comments.spec.ts
@@ -1,10 +1,25 @@
 import * as util from "../util";
 
-test("JSDoc is copied on a function", () => {
+test("Single-line JSDoc is copied on a function", () => {
+    const builder = util.testModule`
+        /** This is a function comment. */
+        function foo() {}
+    `
+        .expectToHaveNoDiagnostics()
+        .expectDiagnosticsToMatchSnapshot();
+
+    const transpiledFile = builder.getLuaResult().transpiledFiles[0];
+    expect(transpiledFile).toBeDefined();
+    const { lua } = transpiledFile;
+    expect(lua).toBeDefined();
+    expect(lua).toContain("This is a function comment.");
+});
+
+test("Multi-line JSDoc with one block is copied on a function", () => {
     const builder = util.testModule`
         /**
          * This is a function comment.
-         * It has multiple lines.
+         * It has more than one line.
          */
         function foo() {}
     `
@@ -15,15 +30,58 @@ test("JSDoc is copied on a function", () => {
     expect(transpiledFile).toBeDefined();
     const { lua } = transpiledFile;
     expect(lua).toBeDefined();
-    expect(lua).toContain("This is a function comment.");
+    expect(lua).toContain("It has more than one line.");
 });
 
-test("JSDoc is copied on a variable", () => {
+test("Multi-line JSDoc with two blocks is copied on a function", () => {
+    const builder = util.testModule`
+        /**
+         * This is a function comment.
+         * It has more than one line.
+         *
+         * It also has more than one block.
+         */
+        function foo() {}
+    `
+        .expectToHaveNoDiagnostics()
+        .expectDiagnosticsToMatchSnapshot();
+
+    const transpiledFile = builder.getLuaResult().transpiledFiles[0];
+    expect(transpiledFile).toBeDefined();
+    const { lua } = transpiledFile;
+    expect(lua).toBeDefined();
+    expect(lua).toContain("It also has more than one block.");
+});
+
+test("JSDoc is copied on a function with tags", () => {
     const builder = util.testModule`
         /**
-         * This is a variable comment.
+         * This is a function comment.
          * It has multiple lines.
+         *
+         * @param arg1 This is the first argument.
+         * @param arg2 This is the second argument.
+         * @returns A very powerful string.
          */
+        function foo(arg1: boolean, arg2: number): string {
+            return "bar";
+        }
+    `
+        .expectToHaveNoDiagnostics()
+        .expectDiagnosticsToMatchSnapshot();
+
+    const transpiledFile = builder.getLuaResult().transpiledFiles[0];
+    expect(transpiledFile).toBeDefined();
+    const { lua } = transpiledFile;
+    expect(lua).toBeDefined();
+    expect(lua).toContain("This is the first argument.");
+    expect(lua).toContain("This is the second argument.");
+    expect(lua).toContain("A very powerful string.");
+});
+
+test("JSDoc is copied on a variable", () => {
+    const builder = util.testModule`
+        /** This is a variable comment. */
         const foo = 123;
     `
         .expectToHaveNoDiagnostics()

From 9ab038757a1b289cb8a72aa1c2f8a7a54a10d6c0 Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sun, 29 May 2022 16:53:19 -0400
Subject: [PATCH 12/13] typo

---
 src/transformation/utils/lua-ast.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/transformation/utils/lua-ast.ts b/src/transformation/utils/lua-ast.ts
index 969ba75a8..f741eba04 100644
--- a/src/transformation/utils/lua-ast.ts
+++ b/src/transformation/utils/lua-ast.ts
@@ -300,7 +300,7 @@ function getJSDocCommentFromTSNode(
     // We want to JSDoc comments to map on to LDoc comments:
     // https://stevedonovan.github.io/ldoc/manual/doc.md.html
     // LDoc comments require that the first line starts with three hyphens.
-    // Thus, need to add one or more hyphens to the first line.
+    // Thus, need to add a hyphen to the first line.
     const firstLine = lines[0];
     if (firstLine.startsWith(" @")) {
         lines.unshift("-");

From c08414423fa0cb4de863643a8db649c7c65405bd Mon Sep 17 00:00:00 2001
From: James <5511220+Zamiell@users.noreply.github.com>
Date: Sun, 29 May 2022 17:13:09 -0400
Subject: [PATCH 13/13] fix: tests

---
 test/unit/__snapshots__/optionalChaining.spec.ts.snap  |  8 ++++++++
 .../__snapshots__/customConstructor.spec.ts.snap       |  2 ++
 .../annotations/__snapshots__/deprecated.spec.ts.snap  | 10 ++++++++++
 test/unit/annotations/deprecated.spec.ts               |  4 ++--
 4 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/test/unit/__snapshots__/optionalChaining.spec.ts.snap b/test/unit/__snapshots__/optionalChaining.spec.ts.snap
index 3d67bf838..26fbcf046 100644
--- a/test/unit/__snapshots__/optionalChaining.spec.ts.snap
+++ b/test/unit/__snapshots__/optionalChaining.spec.ts.snap
@@ -32,9 +32,17 @@ exports[`Unsupported optional chains Builtin prototype method: diagnostics 1`] =
 exports[`Unsupported optional chains Compile members only: code 1`] = `
 "local ____exports = {}
 function ____exports.__main(self)
+    ---
+    -- @compileMembersOnly
     local A = 0
+    ---
+    -- @compileMembersOnly
     local B = 2
+    ---
+    -- @compileMembersOnly
     local C = 3
+    ---
+    -- @compileMembersOnly
     local D = \\"D\\"
     local ____TestEnum_B_0 = TestEnum
     if ____TestEnum_B_0 ~= nil then
diff --git a/test/unit/annotations/__snapshots__/customConstructor.spec.ts.snap b/test/unit/annotations/__snapshots__/customConstructor.spec.ts.snap
index ffd43b2b6..ad79b2eaa 100644
--- a/test/unit/annotations/__snapshots__/customConstructor.spec.ts.snap
+++ b/test/unit/annotations/__snapshots__/customConstructor.spec.ts.snap
@@ -6,6 +6,8 @@ local __TS__Class = ____lualib.__TS__Class
 local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 function ____exports.__main(self)
+    ---
+    -- @customConstructor
     local Point2D = __TS__Class()
     Point2D.name = \\"Point2D\\"
     function Point2D.prototype.____constructor(self)
diff --git a/test/unit/annotations/__snapshots__/deprecated.spec.ts.snap b/test/unit/annotations/__snapshots__/deprecated.spec.ts.snap
index 32c01be9e..87d39ce95 100644
--- a/test/unit/annotations/__snapshots__/deprecated.spec.ts.snap
+++ b/test/unit/annotations/__snapshots__/deprecated.spec.ts.snap
@@ -42,6 +42,8 @@ exports[`extension removed: code 1`] = `
 "local ____lualib = require(\\"lualib_bundle\\")
 local __TS__Class = ____lualib.__TS__Class
 local __TS__ClassExtends = ____lualib.__TS__ClassExtends
+---
+-- @extension
 B = __TS__Class()
 B.name = \\"B\\"
 __TS__ClassExtends(B, A)"
@@ -51,6 +53,8 @@ exports[`extension removed: code 2`] = `
 "local ____lualib = require(\\"lualib_bundle\\")
 local __TS__Class = ____lualib.__TS__Class
 local __TS__ClassExtends = ____lualib.__TS__ClassExtends
+---
+-- @metaExtension
 B = __TS__Class()
 B.name = \\"B\\"
 __TS__ClassExtends(B, A)"
@@ -108,6 +112,8 @@ exports[`pureAbstract removed: diagnostics 1`] = `"main.ts(4,22): error TSTL: '@
 exports[`tuplereturn lambda: code 1`] = `
 "local ____exports = {}
 function ____exports.__main(self)
+    ---
+    -- @tupleReturn
     local function f()
         return {3, 4}
     end
@@ -120,6 +126,8 @@ exports[`tuplereturn lambda: diagnostics 1`] = `"main.ts(2,39): error TSTL: '@tu
 exports[`tuplereturn removed on function declaration: code 1`] = `
 "local ____exports = {}
 function ____exports.__main(self)
+    ---
+    -- @tupleReturn
     local function tuple(self)
         return {3, 5, 1}
     end
@@ -132,6 +140,8 @@ exports[`tuplereturn removed on function declaration: diagnostics 1`] = `"main.t
 exports[`tuplereturn removed: code 1`] = `
 "local ____exports = {}
 function ____exports.__main(self)
+    ---
+    -- @tupleReturn
     local function tuple(self)
         return {3, 5, 1}
     end
diff --git a/test/unit/annotations/deprecated.spec.ts b/test/unit/annotations/deprecated.spec.ts
index f7f0ac9b1..091d681f2 100644
--- a/test/unit/annotations/deprecated.spec.ts
+++ b/test/unit/annotations/deprecated.spec.ts
@@ -4,14 +4,14 @@ import * as util from "../../util";
 test.each(["extension", "metaExtension"])("extension removed", extensionType => {
     util.testModule`
         declare class A {}
-        /** @${extensionType} **/
+        /** @${extensionType} */
         class B extends A {}
     `.expectDiagnosticsToMatchSnapshot([annotationRemoved.code]);
 });
 
 test("phantom removed", () => {
     util.testModule`
-        /** @phantom **/
+        /** @phantom */
         namespace A {
             function nsMember() {}
         }