Merge pull request microsoft#4006 from Microsoft/JSDocCommentScaffolding

Js doc comment templates

Author: zhengbli

src/compiler/binder.ts

@@ -74,7 +74,7 @@ namespace ts {
  // If the current node is a container that also container that also contains locals. Examples:
  //
  // Functions, Methods, Modules, Source-files.
- IsContainerWithLocals  = IsContainer | HasLocals
+ IsContainerWithLocals = IsContainer | HasLocals
  }
 
  export function bindSourceFile(file: SourceFile) {
@@ -1062,4 +1062,4 @@ namespace ts {
  : declareSymbolAndAddToSymbolTable(node, symbolFlags, symbolExcludes);
  }
  }
-}
+}

src/compiler/core.ts

@@ -193,6 +193,13 @@ namespace ts {
  return array[array.length - 1];
  }
 
+ /**
+ * Performs a binary search, finding the index at which 'value' occurs in 'array'.
+ * If no such index is found, returns the 2's-complement of first index at which
+ * number[index] exceeds number.
+ * @param array A sorted array whose first element must be no larger than number
+ * @param number The value to be searched for in the array.
+ */
  export function binarySearch(array: number[], value: number): number {
  let low = 0;
  let high = array.length - 1;

src/compiler/scanner.ts

@@ -319,14 +319,21 @@ namespace ts {
  }
 
  /* @internal */
+ /**
+ * We assume the first line starts at position 0 and 'position' is non-negative.
+ */
  export function computeLineAndCharacterOfPosition(lineStarts: number[], position: number) {
  let lineNumber = binarySearch(lineStarts, position);
  if (lineNumber < 0) {
  // If the actual position was not found,
- // the binary search returns the negative value of the next line start
+ // the binary search returns the 2's-complement of the next line start
  // e.g. if the line starts at [5, 10, 23, 80] and the position requested was 20
- // then the search will return -2
+ // then the search will return -2.
+ //
+ // We want the index of the previous line start, so we subtract 1.
+ // Review 2's-complement if this is confusing.
  lineNumber = ~lineNumber - 1;
+ Debug.assert(lineNumber !== -1, "position cannot precede the beginning of the file");
  }
  return {
  line: lineNumber,
@@ -552,13 +559,17 @@ namespace ts {
  return pos;
  }
 
- // Extract comments from the given source text starting at the given position. If trailing is
- // false, whitespace is skipped until the first line break and comments between that location
- // and the next token are returned.If trailing is true, comments occurring between the given
- // position and the next line break are returned.The return value is an array containing a
- // TextRange for each comment. Single-line comment ranges include the beginning '//' characters
- // but not the ending line break. Multi - line comment ranges include the beginning '/* and
- // ending '*/' characters.The return value is undefined if no comments were found.
+ /**
+ * Extract comments from text prefixing the token closest following `pos`. 
+ * The return value is an array containing a TextRange for each comment.
+ * Single-line comment ranges include the beginning '//' characters but not the ending line break.
+ * Multi - line comment ranges include the beginning '/* and ending '<asterisk>/' characters.
+ * The return value is undefined if no comments were found.
+ * @param trailing 
+ * If false, whitespace is skipped until the first line break and comments between that location
+ * and the next token are returned.
+ * If true, comments occurring between the given position and the next line break are returned.
+ */
  function getCommentRanges(text: string, pos: number, trailing: boolean): CommentRange[] {
  let result: CommentRange[];
  let collecting = trailing || pos === 0;

src/compiler/types.ts

@@ -586,9 +586,9 @@ namespace ts {
  * Several node kinds share function-like features such as a signature,
  * a name, and a body. These nodes should extend FunctionLikeDeclaration.
  * Examples:
- * FunctionDeclaration
- * MethodDeclaration
- * AccessorDeclaration
+ * - FunctionDeclaration
+ * - MethodDeclaration
+ * - AccessorDeclaration
  */
  export interface FunctionLikeDeclaration extends SignatureDeclaration {
  _functionLikeDeclarationBrand: any;

src/harness/fourslash.ts

@@ -1941,6 +1941,32 @@ module FourSlash {
  }
  }
 
+ public verifyDocCommentTemplate(expected?: ts.TextInsertion) {
+ const name = "verifyDocCommentTemplate";
+ let actual = this.languageService.getDocCommentTemplateAtPosition(this.activeFile.fileName, this.currentCaretPosition);
+
+ if (expected === undefined) {
+ if (actual) {
+ this.raiseError(name + ' failed - expected no template but got {newText: \"' + actual.newText + '\" caretOffset: ' + actual.caretOffset + '}');
+ }
+
+ return;
+ }
+ else {
+ if (actual === undefined) {
+ this.raiseError(name + ' failed - expected the template {newText: \"' + actual.newText + '\" caretOffset: ' + actual.caretOffset + '} but got nothing instead');
+ }
+
+ if (actual.newText !== expected.newText) {
+ this.raiseError(name + ' failed - expected insertion:\n' + expected.newText + '\nactual insertion:\n' + actual.newText);
+ }
+
+ if (actual.caretOffset !== expected.caretOffset) {
+ this.raiseError(name + ' failed - expected caretOffset: ' + expected.caretOffset + ',\nactual caretOffset:' + actual.caretOffset);
+ }
+ }
+ }
+
  public verifyMatchingBracePosition(bracePosition: number, expectedMatchPosition: number) {
  this.taoInvalidReason = "verifyMatchingBracePosition NYI";
 
@@ -2808,4 +2834,4 @@ module FourSlash {
  fileName: fileName
  };
  }
-}
+}

src/harness/harnessLanguageService.ts

@@ -381,6 +381,9 @@ module Harness.LanguageService {
  getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: ts.FormatCodeOptions): ts.TextChange[] {
  return unwrapJSONCallResult(this.shim.getFormattingEditsAfterKeystroke(fileName, position, key, JSON.stringify(options)));
  }
+ getDocCommentTemplateAtPosition(fileName: string, position: number): ts.TextInsertion {
+ return unwrapJSONCallResult(this.shim.getDocCommentTemplateAtPosition(fileName, position));
+ }
  getEmitOutput(fileName: string): ts.EmitOutput {
  return unwrapJSONCallResult(this.shim.getEmitOutput(fileName));
  }

src/harness/typeWriter.ts

@@ -71,4 +71,4 @@ class TypeWriterWalker {
  symbol: symbolString
  });
  }
-}
+}

src/server/client.ts

@@ -563,6 +563,10 @@ namespace ts.server {
  getTodoComments(fileName: string, descriptors: TodoCommentDescriptor[]): TodoComment[] {
  throw new Error("Not Implemented Yet."); 
  }
+ 
+ getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion {
+ throw new Error("Not Implemented Yet."); 
+ }
 
  getBraceMatchingAtPosition(fileName: string, position: number): TextSpan[] {
  var lineOffset = this.positionToOneBasedLineOffset(fileName, position);

src/services/services.ts

@@ -1040,6 +1040,8 @@ namespace ts {
  getFormattingEditsForDocument(fileName: string, options: FormatCodeOptions): TextChange[];
  getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: FormatCodeOptions): TextChange[];
 
+ getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion;
+
  getEmitOutput(fileName: string): EmitOutput;
 
  getProgram(): Program;
@@ -1086,6 +1088,12 @@ namespace ts {
  newText: string;
  }
 
+ export interface TextInsertion {
+ newText: string;
+ /** The position in newText the caret should point to after the insertion. */
+ caretOffset: number;
+ }
+
  export interface RenameLocation {
  textSpan: TextSpan;
  fileName: string;
@@ -5486,7 +5494,7 @@ namespace ts {
  symbolToIndex: number[]): void {
 
  let sourceFile = container.getSourceFile();
- let tripleSlashDirectivePrefixRegex = /^\/\/\/\s*</
+ let tripleSlashDirectivePrefixRegex = /^\/\/\/\s*</;
 
  let possiblePositions = getPossibleSymbolReferencePositions(sourceFile, searchText, container.getStart(), container.getEnd());
 
@@ -5502,8 +5510,8 @@ namespace ts {
  // This wasn't the start of a token. Check to see if it might be a 
  // match in a comment or string if that's what the caller is asking
  // for.
- if ((findInStrings && isInString(position)) ||
- (findInComments && isInComment(position))) {
+ if ((findInStrings && isInString(sourceFile, position)) ||
+ (findInComments && isInNonReferenceComment(sourceFile, position))) {
 
  // In the case where we're looking inside comments/strings, we don't have
  // an actual definition. So just use 'undefined' here. Features like
@@ -5567,30 +5575,13 @@ namespace ts {
  return result[index];
  }
 
- function isInString(position: number) {
- let token = getTokenAtPosition(sourceFile, position);
- return token && token.kind === SyntaxKind.StringLiteral && position > token.getStart();
- }
+ function isInNonReferenceComment(sourceFile: SourceFile, position: number): boolean {
+ return isInCommentHelper(sourceFile, position, isNonReferenceComment);
 
- function isInComment(position: number) {
- let token = getTokenAtPosition(sourceFile, position);
- if (token && position < token.getStart()) {
- // First, we have to see if this position actually landed in a comment.
- let commentRanges = getLeadingCommentRanges(sourceFile.text, token.pos);
-
- // Then we want to make sure that it wasn't in a "///<" directive comment
- // We don't want to unintentionally update a file name.
- return forEach(commentRanges, c => {
- if (c.pos < position && position < c.end) {
- let commentText = sourceFile.text.substring(c.pos, c.end);
- if (!tripleSlashDirectivePrefixRegex.test(commentText)) {
- return true;
- }
- }
- });
+ function isNonReferenceComment(c: CommentRange): boolean {
+ let commentText = sourceFile.text.substring(c.pos, c.end);
+ return !tripleSlashDirectivePrefixRegex.test(commentText);
  }
-
- return false;
  }
  }
 
@@ -6817,6 +6808,78 @@ namespace ts {
  return [];
  }
 
+ /**
+ * Checks if position points to a valid position to add JSDoc comments, and if so,
+ * returns the appropriate template. Otherwise returns an empty string.
+ * Valid positions are
+ * - outside of comments, statements, and expressions, and
+ * - preceding a function declaration.
+ *
+ * Hosts should ideally check that:
+ * - The line is all whitespace up to 'position' before performing the insertion.
+ * - If the keystroke sequence "/\*\*" induced the call, we also check that the next
+ * non-whitespace character is '*', which (approximately) indicates whether we added
+ * the second '*' to complete an existing (JSDoc) comment.
+ * @param fileName The file in which to perform the check.
+ * @param position The (character-indexed) position in the file where the check should
+ * be performed.
+ */
+ function getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion {
+ let start = new Date().getTime();
+ let sourceFile = syntaxTreeCache.getCurrentSourceFile(fileName);
+
+ // Check if in a context where we don't want to perform any insertion
+ if (isInString(sourceFile, position) || isInComment(sourceFile, position) || hasDocComment(sourceFile, position)) {
+ return undefined;
+ }
+
+ let tokenAtPos = getTokenAtPosition(sourceFile, position);
+ let tokenStart = tokenAtPos.getStart()
+ if (!tokenAtPos || tokenStart < position) {
+ return undefined;
+ }
+
+ // TODO: add support for:
+ // - methods
+ // - constructors
+ // - class decls
+ let containingFunction = <FunctionDeclaration>getAncestor(tokenAtPos, SyntaxKind.FunctionDeclaration);
+
+ if (!containingFunction || containingFunction.getStart() < position) {
+ return undefined;
+ }
+
+ let parameters = containingFunction.parameters;
+ let posLineAndChar = sourceFile.getLineAndCharacterOfPosition(position);
+ let lineStart = sourceFile.getLineStarts()[posLineAndChar.line];
+
+ let indentationStr = sourceFile.text.substr(lineStart, posLineAndChar.character);
+
+ // TODO: call a helper method instead once PR #4133 gets merged in.
+ const newLine = host.getNewLine ? host.getNewLine() : "\r\n";
+
+ let docParams = parameters.reduce((prev, cur, index) =>
+ prev +
+ indentationStr + " * @param " + (cur.name.kind === SyntaxKind.Identifier ? (<Identifier>cur.name).text : "param" + index) + newLine, "");
+
+ // A doc comment consists of the following
+ // * The opening comment line
+ // * the first line (without a param) for the object's untagged info (this is also where the caret ends up)
+ // * the '@param'-tagged lines
+ // * TODO: other tags.
+ // * the closing comment line
+ // * if the caret was directly in front of the object, then we add an extra line and indentation.
+ const preamble = "/**" + newLine +
+ indentationStr + " * ";
+ let result =
+ preamble + newLine +
+ docParams +
+ indentationStr + " */" +
+ (tokenStart === position ? newLine + indentationStr : "");
+
+ return { newText: result, caretOffset: preamble.length };
+ }
+
  function getTodoComments(fileName: string, descriptors: TodoCommentDescriptor[]): TodoComment[] {
  // Note: while getting todo comments seems like a syntactic operation, we actually 
  // treat it as a semantic operation here. This is because we expect our host to call
@@ -7058,6 +7121,7 @@ namespace ts {
  getFormattingEditsForRange,
  getFormattingEditsForDocument,
  getFormattingEditsAfterKeystroke,
+ getDocCommentTemplateAtPosition,
  getEmitOutput,
  getSourceFile,
  getProgram

src/services/shims.ts

@@ -205,6 +205,11 @@ namespace ts {
  getFormattingEditsForDocument(fileName: string, options: string/*Services.FormatCodeOptions*/): string;
  getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: string/*Services.FormatCodeOptions*/): string;
 
+ /**
+ * Returns JSON-encoded value of the type TextInsertion.
+ */
+ getDocCommentTemplateAtPosition(fileName: string, position: number): string;
+
  getEmitOutput(fileName: string): string;
  }
 
@@ -811,6 +816,13 @@ namespace ts {
  });
  }
 
+ public getDocCommentTemplateAtPosition(fileName: string, position: number): string {
+ return this.forwardJSONCall(
+ "getDocCommentTemplateAtPosition('" + fileName + "', " + position + ")",
+ () => this.languageService.getDocCommentTemplateAtPosition(fileName, position)
+ );
+ }
+
  /// NAVIGATE TO
 
  /** Return a list of symbols that are interesting to navigate to */