#27 - Setting JSDoc description.

- Getting JSDoc tags.

Need to update the documentation for this before releasing. Still a lot of JSDoc stuff not implemented.

src/compiler/base/BodiedNode.ts

@@ -16,7 +16,7 @@ export interface BodiedNode {
     getBody(): Node;
     /**
      * Sets the body text.
-     * @param writerFunction - Function for using a writer to write out the body text.
+     * @param writerFunction - Write the text using the provided writer.
      */
     setBodyText(writerFunction: (writer: CodeBlockWriter) => void): this;
     /**

src/compiler/base/BodyableNode.ts

@@ -20,7 +20,7 @@ export interface BodyableNode {
     getBody(): Node | undefined;
     /**
      * Sets the body text. A body is required to do this operation.
-     * @param writerFunction - Function for using a writer to write out the body text.
+     * @param writerFunction - Write the text using the provided writer.
      */
     setBodyText(writerFunction: (writer: CodeBlockWriter) => void): this;
     /**

src/compiler/base/DocumentationableNode.ts

@@ -50,7 +50,7 @@ export function DocumentationableNode<T extends Constructor<DocumentationableNod
             if (docCommentNodes.length === 0)
                 return undefined;
 
-            const texts = docCommentNodes.map(n => (n.compilerNode.comment || "").trim());
+            const texts = docCommentNodes.map(n => (n.getComment() || "").trim());
             return texts.filter(t => t.length > 0).join(this.global.manipulationSettings.getNewLineKind());
         }
 

src/compiler/base/name/DeclarationNamedNode.ts

@@ -21,6 +21,10 @@ export interface DeclarationNamedNode {
      * Gets the name.
      */
     getName(): string | undefined;
+    /**
+     * Gets the name or throws if it doens't exist.
+     */
+    getNameOrThrow(): string;
     /**
      * Renames the name.
      * @param text - Text to set as the name.
@@ -52,6 +56,10 @@ export function DeclarationNamedNode<T extends Constructor<DeclarationNamedNodeE
             }
         }
 
+        getNameOrThrow() {
+            return errors.throwIfNullOrUndefined(this.getName(), "Expected to find a name.");
+        }
+
         getName() {
             const nameNode = this.getNameIdentifier();
             return nameNode == null ? undefined : nameNode.getText();

src/compiler/common/Node.ts

@@ -672,13 +672,11 @@ export class Node<NodeType extends ts.Node = ts.Node> implements Disposable {
     }
 
     /**
-     * Gets the position of the start of the line that this node is on.
+     * Gets the position of the start of the line that this node starts on.
      */
     getStartLinePos() {
         const sourceFileText = this.sourceFile.getFullText();
-        const startPos = this.getStart();
-
-        return getPreviousMatchingPos(sourceFileText, startPos, char => char === "\n");
+        return getPreviousMatchingPos(sourceFileText, this.getStart(), char => char === "\n");
     }
 
     /**
@@ -705,7 +703,7 @@ export class Node<NodeType extends ts.Node = ts.Node> implements Disposable {
      * Replaces the text of the current node with new text.
      *
      * This will dispose the current node and return a new node that can be asserted or type guarded to the correct type.
-     * @param writerFunction - Writer function to replace the text with.
+     * @param writerFunction - Write the text using the provided writer.
      * @returns The new node.
      */
     replaceWithText(writerFunction: (writer: CodeBlockWriter) => void): Node;

src/compiler/doc.ts

@@ -1 +1,10 @@
 export * from "./doc/JSDoc";
+export * from "./doc/JSDocTag";
+export * from "./doc/JSDocUnknownTag";
+export * from "./doc/JSDocAugmentsTag";
+export * from "./doc/JSDocClassTag";
+export * from "./doc/JSDocReturnTag";
+export * from "./doc/JSDocTypeTag";
+export * from "./doc/JSDocTypedefTag";
+export * from "./doc/JSDocPropertyTag";
+export * from "./doc/JSDocParameterTag";

src/compiler/doc/JSDoc.ts

@@ -1,11 +1,60 @@
 import * as ts from "typescript";
-import {removeChildren} from "./../../manipulation";
+import CodeBlockWriter from "code-block-writer";
+import {removeChildren, replaceTextPossiblyCreatingChildNodes} from "./../../manipulation";
+import {getPreviousMatchingPos} from "./../../manipulation/textSeek";
+import {getTextFromStringOrWriter} from "./../../utils";
 import {Node} from "./../common";
 
 /**
- * A js doc node.
+ * JS doc node.
  */
 export class JSDoc extends Node<ts.JSDoc> {
+    /**
+     * Gets the tags of the JSDoc.
+     */
+    getTags(): Node[] {
+        const tags = this.compilerNode.tags;
+        if (tags == null)
+            return [];
+        return tags.map(t => this.global.compilerFactory.getNodeFromCompilerNode(t, this.sourceFile)) as Node[];
+    }
+
+    /**
+     * Gets the comment.
+     */
+    getComment() {
+        return this.compilerNode.comment;
+    }
+
+    /**
+     * Sets the comment.
+     * @param writerFunction - Write the text using the provided writer.
+     */
+    setComment(writerFunction: (writer: CodeBlockWriter) => void): this;
+    /**
+     * Sets the comment.
+     * @param text - Text of the comment.
+     */
+    setComment(text: string): this;
+    setComment(textOrWriterFunction: string | ((writer: CodeBlockWriter) => void)) {
+        const tags = this.getTags();
+        const startEditPos = this.getStart() + 3;
+        const endEditPos = tags.length > 0 ? getPreviousMatchingPos(this.sourceFile.getFullText(), tags[0].getStart(), c => c === "*") - 1 : this.getEnd() - 2;
+        const indentationText = this.getIndentationText();
+        const newLineKind = this.global.manipulationSettings.getNewLineKind();
+        const text = getTextFromStringOrWriter(this.global.manipulationSettings, textOrWriterFunction);
+        const newText = newLineKind + text.split(/\r?\n/).map(l => `${indentationText} * ${l}`).join(newLineKind) + newLineKind + indentationText + " ";
+
+        replaceTextPossiblyCreatingChildNodes({
+            parent: this,
+            newText,
+            replacePos: startEditPos,
+            replacingLength: endEditPos - startEditPos
+        });
+
+        return this;
+    }
+
     /**
      * Removes this JSDoc.
      */

src/compiler/doc/JSDocAugmentsTag.ts

@@ -0,0 +1,9 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+
+/**
+ * JS doc augments tag node.
+ */
+export class JSDocAugmentsTag extends JSDocTag<ts.JSDocAugmentsTag> {
+    // todo: helper methods
+}

src/compiler/doc/JSDocClassTag.ts

@@ -0,0 +1,8 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+
+/**
+ * JS doc class tag node.
+ */
+export class JSDocClassTag extends JSDocTag<ts.JSDocClassTag> {
+}

src/compiler/doc/JSDocParameterTag.ts

@@ -0,0 +1,10 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+import {JSDocPropertyLikeTag} from "./base";
+
+export const JSDocParameterTagBase = JSDocPropertyLikeTag(JSDocTag);
+/**
+ * JS doc parameter tag node.
+ */
+export class JSDocParameterTag extends JSDocParameterTagBase<ts.JSDocParameterTag> {
+}

src/compiler/doc/JSDocPropertyTag.ts

@@ -0,0 +1,10 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+import {JSDocPropertyLikeTag} from "./base";
+
+export const JSDocPropertyTagBase = JSDocPropertyLikeTag(JSDocTag);
+/**
+ * JS doc property tag node.
+ */
+export class JSDocPropertyTag extends JSDocPropertyTagBase<ts.JSDocPropertyTag> {
+}

src/compiler/doc/JSDocReturnTag.ts

@@ -0,0 +1,9 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+
+/**
+ * JS doc return tag node.
+ */
+export class JSDocReturnTag extends JSDocTag<ts.JSDocReturnTag> {
+    // todo: helper methods
+}

src/compiler/doc/JSDocTag.ts

@@ -0,0 +1,28 @@
+import * as ts from "typescript";
+import {Node, Identifier} from "./../common";
+
+/**
+ * JS doc tag node.
+ */
+export class JSDocTag<NodeType extends ts.JSDocTag = ts.JSDocTag> extends Node<NodeType> {
+    /**
+     * Gets the at token.
+     */
+    getAtToken() {
+        return this.global.compilerFactory.getNodeFromCompilerNode(this.compilerNode.atToken, this.sourceFile) as Node;
+    }
+
+    /**
+     * Gets the tag name identifier.
+     */
+    getTagNameIdentifier() {
+        return this.global.compilerFactory.getNodeFromCompilerNode(this.compilerNode.tagName, this.sourceFile) as Identifier;
+    }
+
+    /**
+     * Gets the tag's comment.
+     */
+    getComment() {
+        return this.compilerNode.comment;
+    }
+}

src/compiler/doc/JSDocTypeTag.ts

@@ -0,0 +1,9 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+
+/**
+ * JS doc type tag node.
+ */
+export class JSDocTypeTag extends JSDocTag<ts.JSDocTypeTag> {
+    // todo: helper methods
+}

src/compiler/doc/JSDocTypedefTag.ts

@@ -0,0 +1,9 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+
+/**
+ * JS doc type def tag node.
+ */
+export class JSDocTypedefTag extends JSDocTag<ts.JSDocTypedefTag> {
+    // todo: helper methods
+}

src/compiler/doc/JSDocUnknownTag.ts

@@ -0,0 +1,8 @@
+import * as ts from "typescript";
+import {JSDocTag} from "./JSDocTag";
+
+/**
+ * JS doc unknown tag node.
+ */
+export class JSDocUnknownTag extends JSDocTag<ts.JSDocUnknownTag> {
+}

src/compiler/doc/base.ts

@@ -0,0 +1 @@
+export * from "./base/JSDocPropertyLikeTag";

src/compiler/doc/base/JSDocPropertyLikeTag.ts

@@ -0,0 +1,15 @@
+import * as ts from "typescript";
+import {Constructor} from "./../../../Constructor";
+import {Node} from "./../../common";
+
+export type JSDocPropertyLikeTagExtensionType = Node /*& ModifierableNode*/;
+
+export interface JSDocPropertyLikeTag {
+    // todo: methods
+}
+
+export function JSDocPropertyLikeTag<T extends Constructor<JSDocPropertyLikeTagExtensionType>>(Base: T): Constructor<JSDocPropertyLikeTag> & T {
+    return class extends Base implements JSDocPropertyLikeTag {
+        // todo: methods
+    };
+}

src/factories/nodeToWrapperMappings.ts

@@ -44,5 +44,12 @@ export const nodeToWrapperMappings: { [key: number]: any } = {
     [ts.SyntaxKind.VariableStatement]: compiler.VariableStatement,
     [ts.SyntaxKind.JSDocComment]: compiler.JSDoc,
     [ts.SyntaxKind.FirstTypeNode]: compiler.TypeNode,
-    [ts.SyntaxKind.LastTypeNode]: compiler.TypeNode
+    [ts.SyntaxKind.LastTypeNode]: compiler.TypeNode,
+    [ts.SyntaxKind.JSDocTag]: compiler.JSDocUnknownTag,
+    [ts.SyntaxKind.JSDocAugmentsTag]: compiler.JSDocAugmentsTag,
+    [ts.SyntaxKind.JSDocClassTag]: compiler.JSDocClassTag,
+    [ts.SyntaxKind.JSDocReturnTag]: compiler.JSDocReturnTag,
+    [ts.SyntaxKind.JSDocTypeTag]: compiler.JSDocTypeTag,
+    [ts.SyntaxKind.JSDocTypedefTag]: compiler.JSDocTypedefTag,
+    [ts.SyntaxKind.JSDocPropertyTag]: compiler.JSDocPropertyTag
 };

src/manipulation/code/getIndentedText.ts

@@ -11,7 +11,7 @@ export interface GetIndentedTextOptions {
 export function getIndentedText(opts: GetIndentedTextOptions) {
     const {textOrWriterFunction, manipulationSettings, indentationText} = opts;
     const newLineKind = manipulationSettings.getNewLineKind();
-    const originalText = getTextFromStringOrWriter(manipulationSettings, textOrWriterFunction) || "";
+    const originalText = getTextFromStringOrWriter(manipulationSettings, textOrWriterFunction);
     if (originalText.length > 0)
         return originalText.split(/\r?\n/).map(t => t.length > 0 ? indentationText + t : t).join(newLineKind);
     return originalText;

src/manipulation/insertion/getNewReplacementSourceFile.ts → src/manipulation/getNewReplacementSourceFile.ts

@@ -1,4 +1,4 @@
-import {Node, SourceFile} from "./../../compiler";
+import {Node, SourceFile} from "./../compiler";
 
 export interface GetNewReplacementSourceFileOptions {
     insertPos: number;

src/manipulation/insertion/insertIntoCreatableSyntaxList.ts

@@ -1,6 +1,6 @@
 import {Node} from "./../../compiler";
 import {replaceTreeCreatingSyntaxList, replaceTreeWithChildIndex} from "./../tree";
-import {getNewReplacementSourceFile} from "./getNewReplacementSourceFile";
+import {getNewReplacementSourceFile} from "./../getNewReplacementSourceFile";
 import {insertSyntaxList} from "./insertSyntaxList";
 import {insertIntoParent} from "./insertIntoParent";
 

src/manipulation/insertion/insertIntoParent.ts

@@ -1,6 +1,6 @@
 import {Node} from "./../../compiler";
 import {replaceTreeWithChildIndex} from "./../tree";
-import {getNewReplacementSourceFile} from "./getNewReplacementSourceFile";
+import {getNewReplacementSourceFile} from "./../getNewReplacementSourceFile";
 
 export interface InsertIntoParentOptions {
     insertPos: number;

src/manipulation/insertion/insertIntoParentTextRange.ts

@@ -1,6 +1,6 @@
 import {Node} from "./../../compiler";
 import {replaceTreeWithRange} from "./../tree";
-import {getNewReplacementSourceFile} from "./getNewReplacementSourceFile";
+import {getNewReplacementSourceFile} from "./../getNewReplacementSourceFile";
 
 export interface InsertIntoParentTextRangeOptions {
     insertPos: number;

src/manipulation/insertion/insertSyntaxList.ts

@@ -1,6 +1,6 @@
 import {Node} from "./../../compiler";
 import {replaceTreeCreatingSyntaxList} from "./../tree";
-import {getNewReplacementSourceFile} from "./getNewReplacementSourceFile";
+import {getNewReplacementSourceFile} from "./../getNewReplacementSourceFile";
 
 export interface InsertSyntaxListOptions {
     insertPos: number;

src/manipulation/removal/unwrapNode.ts

@@ -2,7 +2,7 @@
 import {Node} from "./../../compiler";
 import {isStringNode} from "./../../utils";
 import {replaceTreeUnwrappingNode} from "./../tree";
-import {getNewReplacementSourceFile} from "./../insertion/getNewReplacementSourceFile";
+import {getNewReplacementSourceFile} from "./../getNewReplacementSourceFile";
 
 export function unwrapNode(node: Node) {
     const tempSourceFile = getNewReplacementSourceFile({

src/manipulation/replaction.ts

@@ -1,2 +1,3 @@
 export * from "./replaction/replaceNodeText";
 export * from "./replaction/replaceSourceFileTextForFormatting";
+export * from "./replaction/replaceTextPossiblyCreatingChildNodes";

src/manipulation/replaction/replaceTextPossiblyCreatingChildNodes.ts

@@ -0,0 +1,30 @@
+import {Node} from "./../../compiler";
+import {replaceTreeWithRange} from "./../tree";
+import {getNewReplacementSourceFile} from "./../getNewReplacementSourceFile";
+
+export interface ReplaceTextPossiblyCreatingChildNodesOptions {
+    replacePos: number;
+    replacingLength: number;
+    newText: string;
+    parent: Node;
+}
+
+/**
+ * Replaces a node text while possibly creating new child nodes.
+ */
+export function replaceTextPossiblyCreatingChildNodes(opts: ReplaceTextPossiblyCreatingChildNodesOptions) {
+    const {replacePos, replacingLength, newText, parent} = opts;
+    const tempSourceFile = getNewReplacementSourceFile({
+        sourceFile: parent.getSourceFile(),
+        insertPos: replacePos,
+        replacingLength,
+        newText
+    });
+
+    replaceTreeWithRange({
+        parent,
+        replacementSourceFile: tempSourceFile,
+        start: replacePos,
+        end: replacePos + newText.length
+    });
+}