Merge existing JSDoc comments (#27978)

* Correct indentation, using correct (I hope) indentation code

Note that part of the code, in formatting.ts, is cloned but should be
extracted to a function instead.

* Remove some possibly-superfluous code

But I see 4 failures with whitespace, so perhaps not.

* Restrict indentation change to avoid breaking baselines

The indentation code is very complex so I'm just going to avoid breaking
our single-line tests for now, plus add a simple jsdoc test to show that
multiline jsdoc indentation isn't destroyed in the common case.

* Switched over to construction for @return/@type

Still doesn't merge correctly though

* Add @return tags to emitter

* Merge multiple jsdocs

(not for @param yet)

* Merge multiple jsdoc for parameters too

* Emit more jsdoc tags

Not all of them; I got cold feet since I'll have to write tests for
them. I'll do that tomorrow.

* Many fixes to JSDoc emit

And single tests (at least) for all tags

* Cleanup in textChanges.ts

* Cleanup in formatting.ts

(Plus a little more in textChanges.ts)

* Cleanup in inferFromUsage.ts

* Fix minor omissions

* Separate merged top-level JSDoc comments with \n

instead of space.

* Don't delete intrusive non-jsdoc comments

* Cleanup from PR comments

1. Refactor emit code into smaller functions.
2. Preceding-whitespace utility is slightly easier to use.
3. Better casts and types in inferFromUsage make it easier to read.

* Fix bogus newline

* Use @andy-ms' cleanup annotateJSDocParameters

tests/cases/fourslash/codeFixInferFromUsageExistingJSDoc.ts

@@ -0,0 +1,95 @@
+/// <reference path='fourslash.ts' />
+// @allowJs: true
+// @checkJs: true
+// @noImplicitAny: true
+// @strictNullChecks: false
+// @Filename: important.js
+
+/////** @param x no types here! */
+/////**
+//// * 1
+//// * @param x a duplicate!
+//// * @param y yy
+//// */
+/////**
+//// * 2
+//// * @param z zz
+//// */
+////function f(x) {
+////    return x * 1
+////}
+////
+////var o = {
+////    /** 1
+////     * @return First one
+////     */
+////    // intrusive comment (should not be deleted)
+////    /** 2
+////     * @see also
+////     */
+////    /** 3
+////     * @return Second one
+////     * @extends {C<number>} nothing really
+////     * @class
+////     * @this {*} doesn't make sense here
+////     * @enum wat
+////     */
+////    /**
+////     * @typedef {number} Meter or something
+////     * @typedef {Object} Position Comment!
+////     * @property {number} x what a horrible place for a type
+////     * @property {number} y please don't do this
+////     */
+////    /**
+////     * @template {string} T postfix comment
+////     * @callback Action not sure what this will do
+////     * @param {T} thing
+////     * @returns {string} oh no
+////     */
+////    get m() { return undefined }
+////}
+////o.m = 1
+
+verify.codeFixAll({
+    fixId: "inferFromUsage",
+    fixAllDescription: "Infer all types from usage",
+    newFileContent:
+`/**
+ * 1
+ * 2
+ * @param {number} x no types here!
+ * @param x a duplicate!
+ * @param y yy
+ * @param z zz
+ */
+function f(x) {
+    return x * 1
+}
+
+var o = {
+    // intrusive comment (should not be deleted)
+    /**
+     * 1
+     * 2
+     * 3
+     * @returns {number} First one
+     * @see also
+     * @return Second one
+     * @extends {C<number>} nothing really
+     * @class
+     * @this {*} doesn't make sense here
+     * @enum {wat}
+     * @typedef {number} Meter or something
+     * @typedef {Object} Position Comment!
+     * @property {number} x what a horrible place for a type
+     * @property {number} y please don't do this
+     * @template {string} T postfix comment
+     * @callback Action not sure what this will do
+     * @param {T} thing
+     * @returns {string} oh no
+     */
+    get m() { return undefined }
+}
+o.m = 1`,
+});
+

tests/cases/fourslash/codeFixInferFromUsageMemberJS.ts

@@ -7,26 +7,34 @@
 // @Filename: important.js
 ////class C {
 ////    constructor() {
-////        [|this.p|] = undefined;
+////        /** this is fine */
+////        this.p = undefined;
+////        this.q = undefined
 ////    }
 ////    method() {
 ////        this.p.push(1)
+////        this.q.push(1);
 ////    }
 ////}
 
 // Note: Should be number[] | undefined, but inference currently privileges assignments
 // over usage (even when the only result is undefined) and infers only undefined.
-verify.codeFix({
-    description: "Infer type of 'p' from usage",
-    index: 2,
+verify.codeFixAll({
+    fixId: "inferFromUsage",
+    fixAllDescription: "Infer all types from usage",
     newFileContent:
 `class C {
     constructor() {
-        /** @type {undefined} */
+        /**
+         * this is fine
+         * @type {undefined}
+         */
         this.p = undefined;
+        /** @type {undefined} */
+        this.q = undefined
     }
     method() {
         this.p.push(1)
+        this.q.push(1);
     }
-}`
-});
+}`});

tests/cases/fourslash/codeFixInferFromUsagePartialParameterListJS.ts

@@ -19,8 +19,6 @@ verify.codeFix({
     newFileContent:
 `/**
  * @param {*} y
- */
-/**
  * @param {number} x
  * @param {number} z
  */

tests/cases/fourslash/codeFixInferFromUsageRestParam2JS.ts

@@ -17,8 +17,8 @@ verify.codeFix({
     description: "Infer parameter types from usage",
     index: 2,
     newFileContent:
-`/** @param {number} a */
-/**
+`/**
+ * @param {number} a
  * @param {(string | boolean)[]} rest
  */
 function f(a, ...rest){

tests/cases/fourslash/codeFixInferFromUsageRestParam3JS.ts

@@ -14,8 +14,8 @@ verify.codeFix({
     description: "Infer parameter types from usage",
     index: 2,
     newFileContent:
-`/** @param {number} a */
-/**
+`/**
+ * @param {number} a
  * @param {number[]} rest
  */
 function f(a, ...rest){

tests/cases/fourslash/codeFixInferFromUsageRestParamJS.ts

@@ -17,8 +17,8 @@ verify.codeFix({
     description: "Infer parameter types from usage",
     index: 4,
     newFileContent:
-`/** @param {number} a */
-/**
+`/**
+ * @param {number} a
  * @param {string[]} rest
  */
 function f(a: number, ...rest){

tests/cases/fourslash/codeFixInferFromUsageSingleLineClassJS.ts

@@ -14,9 +14,9 @@ verify.codeFix({
     index: 2,
     newFileContent:
 `class C {/**
-          * @param {number} x
-          */
-         m(x) {return x;}}
+ * @param {number} x
+ */
+m(x) {return x;}}
 var c = new C()
 c.m(1)`,
 });

tests/cases/fourslash/formatDocumentWithJSDoc.ts

@@ -0,0 +1,29 @@
+/// <reference path="fourslash.ts" />
+
+/////**
+//// * JSDoc for things
+//// */
+////function f() {
+////    /** more
+////        jsdoc */
+////    var t;
+////    /**
+////     * multiline
+////     */
+////    var multiline;
+////}
+
+format.document();
+
+verify.currentFileContentIs(`/**
+ * JSDoc for things
+ */
+function f() {
+    /** more
+        jsdoc */
+    var t;
+    /**
+     * multiline
+     */
+    var multiline;
+}`);

tests/cases/fourslash/formatDocumentWithTrivia.ts

@@ -1,9 +1,9 @@
 /// <reference path="fourslash.ts" />
 
 ////  
-////// whitespace below   
+////// 1 below   
 ////    
-////// whitespace above   
+////// 2 above   
 ////    
 ////let x;
 ////  
@@ -11,25 +11,25 @@
 ////  
 ////let y;
 ////  
-////// whitespace above again
+////// 3 above
 ////   
 ////while (true) {
 ////    while (true) {
 ////    }
 ////      
-////    // whitespace above   
+////    // 4 above   
 ////}
 ////  
-////// whitespace above again  
+////// 5 above  
 ////   
 ////   
 
 format.document();
 
 verify.currentFileContentIs(`
-// whitespace below   
+// 1 below   
 
-// whitespace above   
+// 2 above   
 
 let x;
 
@@ -37,15 +37,15 @@ let x;
 
 let y;
 
-// whitespace above again
+// 3 above
 
 while (true) {
     while (true) {
     }
 
-    // whitespace above   
+    // 4 above   
 }
 
-// whitespace above again  
+// 5 above  
 
 `);

tests/cases/fourslash/smartIndentOnFunctionParameters.ts

@@ -2,12 +2,12 @@
 
 ////function foo(a,
 ////        /*2*/b,/*0*/
-////             //comment/*3*/
+////             //ABC/*3*/
 ////    /*4*/c
 ////    ) {
 ////};
 ////var x = [
-////    /*5*///comment/*1*/
+////    /*5*///DEF/*1*/
 ////    1,/*6*/
 ////        2/*7*/
 ////]
@@ -17,14 +17,14 @@ verify.indentationIs(4);
 goTo.marker("2");
 verify.currentLineContentIs("    b,");
 goTo.marker("3");
-verify.currentLineContentIs("             //comment");
+verify.currentLineContentIs("             //ABC");
 goTo.marker("4");
 verify.currentLineContentIs("    c");
 goTo.marker("1");
 edit.insert("\n");
 verify.indentationIs(4);
 goTo.marker("5");
-verify.currentLineContentIs("    //comment");
+verify.currentLineContentIs("    //DEF");
 goTo.marker("6");
 verify.currentLineContentIs("    1,");
 goTo.marker("7");