Support JSDoc @function

[mjbvz]

From: microsoft/vscode#21321

TypeScript Version: 2.2.1 / nightly (2.2.0-dev.201xxxxx)

Code

// test-module.d.ts
declare module 'test-module' {
    declare function func<T>(c: T): (y: any) => any;
}

// example.js
import { func } from 'test-module';

/** 
 * @function
 * @param {number} c first number
 * @returns {number} result
 */
const thisDoesNot = func(1);

Expected behavior:
The JSDoc specifications give thisDoesNot a type of (c: number) => number

Actual behavior:
The type from the *.d.ts file is preferred instead, giving thisDoesNot a type of (c: any) => any

[mjbvz]

Also, the param name and param description from the jsdoc should override those from the *.d.ts file. For example, if the code were :

/** 
 * @function
 * @param {number} myNewParamName Description of param
 * @returns {number} result
 */
const thisDoesNot = func(1);

For signature help on thisDoesNot, we'd want to show the information provided by the jsdoc for myNewParamName

[sandersn]

We should actually treat any @param/@return on a variable declaration as a type annotation. If we do that, I don't think that @function needs any special support.

#36633 requests this behaviour, and #31313 implies that it wants this behaviour for @class and several other tags.