feat: Ability to add js docs with a writer function directly from the…

… method.

Ex. `classDec.addJsDoc(writer => writer.write("My doc."));`

lib/ts-simple-ast.d.ts

@@ -2303,24 +2303,24 @@ export interface JSDocableNode {
      * Adds a JS doc.
      * @param structure - Structure to add.
      */
-    addJsDoc(structure: JSDocStructure | string): JSDoc;
+    addJsDoc(structure: JSDocStructure | string | WriterFunction): JSDoc;
     /**
      * Adds JS docs.
      * @param structures - Structures to add.
      */
-    addJsDocs(structures: (JSDocStructure | string)[]): JSDoc[];
+    addJsDocs(structures: (JSDocStructure | string | WriterFunction)[]): JSDoc[];
     /**
      * Inserts a JS doc.
      * @param index - Child index to insert at.
      * @param structure - Structure to insert.
      */
-    insertJsDoc(index: number, structure: JSDocStructure | string): JSDoc;
+    insertJsDoc(index: number, structure: JSDocStructure | string | WriterFunction): JSDoc;
     /**
      * Inserts JS docs.
      * @param index - Child index to insert at.
      * @param structures - Structures to insert.
      */
-    insertJsDocs(index: number, structures: (JSDocStructure | string)[]): JSDoc[];
+    insertJsDocs(index: number, structures: (JSDocStructure | string | WriterFunction)[]): JSDoc[];
 }
 
 export declare type JSDocableNodeExtensionType = Node<ts.Node & {

src/compiler/base/JSDocableNode.ts

@@ -4,6 +4,7 @@ import { Constructor } from "../../types";
 import { ts } from "../../typescript";
 import { ArrayUtils } from "../../utils";
 import { callBaseFill } from "../callBaseFill";
+import { WriterFunction } from "../../types";
 import { Node } from "../common";
 import { JSDoc } from "../doc/JSDoc";
 
@@ -18,24 +19,24 @@ export interface JSDocableNode {
      * Adds a JS doc.
      * @param structure - Structure to add.
      */
-    addJsDoc(structure: JSDocStructure | string): JSDoc;
+    addJsDoc(structure: JSDocStructure | string | WriterFunction): JSDoc;
     /**
      * Adds JS docs.
      * @param structures - Structures to add.
      */
-    addJsDocs(structures: (JSDocStructure | string)[]): JSDoc[];
+    addJsDocs(structures: (JSDocStructure | string | WriterFunction)[]): JSDoc[];
     /**
      * Inserts a JS doc.
      * @param index - Child index to insert at.
      * @param structure - Structure to insert.
      */
-    insertJsDoc(index: number, structure: JSDocStructure | string): JSDoc;
+    insertJsDoc(index: number, structure: JSDocStructure | string | WriterFunction): JSDoc;
     /**
      * Inserts JS docs.
      * @param index - Child index to insert at.
      * @param structures - Structures to insert.
      */
-    insertJsDocs(index: number, structures: (JSDocStructure | string)[]): JSDoc[];
+    insertJsDocs(index: number, structures: (JSDocStructure | string | WriterFunction)[]): JSDoc[];
 }
 
 export function JSDocableNode<T extends Constructor<JSDocableNodeExtensionType>>(Base: T): Constructor<JSDocableNode> & T {
@@ -47,19 +48,19 @@ export function JSDocableNode<T extends Constructor<JSDocableNodeExtensionType>>
             return nodes.map(n => this.getNodeFromCompilerNode(n));
         }
 
-        addJsDoc(structure: JSDocStructure | string) {
+        addJsDoc(structure: JSDocStructure | string | WriterFunction) {
             return this.addJsDocs([structure])[0];
         }
 
-        addJsDocs(structures: (JSDocStructure | string)[]) {
+        addJsDocs(structures: (JSDocStructure | string | WriterFunction)[]) {
             return this.insertJsDocs(getEndIndexFromArray(this.compilerNode.jsDoc), structures);
         }
 
-        insertJsDoc(index: number, structure: JSDocStructure | string) {
+        insertJsDoc(index: number, structure: JSDocStructure | string | WriterFunction) {
             return this.insertJsDocs(index, [structure])[0];
         }
 
-        insertJsDocs(index: number, structures: (JSDocStructure | string)[]) {
+        insertJsDocs(index: number, structures: (JSDocStructure | string | WriterFunction)[]) {
             if (ArrayUtils.isNullOrEmpty(structures))
                 return [];
 

src/structurePrinters/doc/JSDocStructurePrinter.ts

@@ -1,10 +1,11 @@
 import { CodeBlockWriter } from "../../codeBlockWriter";
 import { JSDocStructure } from "../../structures";
+import { WriterFunction } from "../../types";
 import { getTextFromStringOrWriter } from "../../utils";
 import { FactoryStructurePrinter } from "../FactoryStructurePrinter";
 
 export class JSDocStructurePrinter extends FactoryStructurePrinter<JSDocStructure | string> {
-    printText(writer: CodeBlockWriter, structure: JSDocStructure | string) {
+    printText(writer: CodeBlockWriter, structure: JSDocStructure | string | WriterFunction) {
         const lines = getText().split(/\r?\n/);
         writer.writeLine("/**");
         for (const line of lines)
@@ -14,11 +15,16 @@ export class JSDocStructurePrinter extends FactoryStructurePrinter<JSDocStructur
         function getText() {
             if (typeof structure === "string")
                 return structure;
-            return getTextFromStringOrWriter(new CodeBlockWriter(writer.getOptions()), structure.description);
+            const tempWriter = new CodeBlockWriter(writer.getOptions());
+            if (typeof structure === "function") {
+                structure(tempWriter);
+                return tempWriter.toString();
+            }
+            return getTextFromStringOrWriter(tempWriter, structure.description);
         }
     }
 
-    printDocs(writer: CodeBlockWriter, structures: (JSDocStructure | string)[] | undefined) {
+    printDocs(writer: CodeBlockWriter, structures: (JSDocStructure | string | WriterFunction)[] | undefined) {
         if (structures == null)
             return;
 

src/tests/compiler/base/jsDocableNodeTests.ts

@@ -1,5 +1,6 @@
 import { expect } from "chai";
 import { ClassDeclaration, FunctionDeclaration, JSDocableNode, Node, VariableStatement } from "../../../compiler";
+import { WriterFunction } from "../../../types";
 import { JSDocableNodeStructure, JSDocStructure } from "../../../structures";
 import { SyntaxKind } from "../../../typescript";
 import { getInfoFromText, getInfoFromTextWithDescendant } from "../testHelpers";
@@ -52,7 +53,9 @@ describe(nameof(JSDocableNode), () => {
     });
 
     describe(nameof<JSDocableNode>(n => n.insertJsDocs), () => {
-        function doTest(startCode: string, insertIndex: number, structures: (JSDocStructure | string)[], expectedCode: string, syntaxKind = SyntaxKind.FunctionDeclaration) {
+        function doTest(startCode: string, insertIndex: number, structures: (JSDocStructure | string | WriterFunction)[],
+            expectedCode: string, syntaxKind = SyntaxKind.FunctionDeclaration)
+        {
             const {descendant, sourceFile} = getInfoFromTextWithDescendant(startCode, syntaxKind);
             const result = (descendant as any as JSDocableNode).insertJsDocs(insertIndex, structures);
             expect(result.length).to.equal(structures.length);
@@ -74,7 +77,7 @@ describe(nameof(JSDocableNode), () => {
         });
 
         it("should insert in the middle", () => {
-            doTest("/**\n * Desc1\n */\n/**\n * Desc3\n */\nfunction identifier() {}", 1, [{ description: "Desc2" }],
+            doTest("/**\n * Desc1\n */\n/**\n * Desc3\n */\nfunction identifier() {}", 1, [writer => writer.write("Desc2")],
                 "/**\n * Desc1\n */\n/**\n * Desc2\n */\n/**\n * Desc3\n */\nfunction identifier() {}");
         });