JSDoc: function declarations are not type checked

[OliverJAsh]

TypeScript Version: 2.3.4

Code

{
  /** @type {function(number): number} */
  const foo = (x) => x
  foo('f') // error, good!

  /** @type {function(number): number} */
  function foo2(x) { return x }
  foo2('f') // expected error, but got none
}

[ikatyang]

In my opinion, function declarations can't use the @types tag, since functions can only be function type, just like:

declare const foo: (x: number) => number;
declare function foo2(x: number): number;

You can't use type declaration for function declaration, you have to use @param, @return.

{
  /** @type {function (number): number} */
  const foo = (x) => x
  foo('f') // error, good!

  /**
   * @param {number} x
   * @return {number}
   */
  function foo2(x) { return x }
  foo2('f') // error, as expected
}

[OliverJAsh]

@ikatyang Interesting, how would you add a property to a function declaration? I've tried using @property, to no avail:

  /**
   * @param {number} x
   * @property {number} bar
   * @return {number}
   */
  function foo2(x) { return x }
  foo2('f') // error, as expected
  foo2.bar = 1; // unexpected error

[ikatyang]

Ah, it works fine for me even without @property {number} bar.

[OliverJAsh]

@ikatyang I think what you're seeing is related to a different bug with JSDoc: #16239 (comment)

If you wrap that code in a block, it will give you the unexpected error:

{
  /**
   * @param {number} x
   * @return {number}
   */
  function foo2(x) { return x }
  foo2('f') // error, as expected
  foo2.bar = 1; // unexpected error
}

{
  /**
   * @param {number} x
   * @property {number} bar
   * @return {number}
   */
  function foo2(x) { return x }
  foo2('f') // error, as expected
  foo2.bar = 1; // unexpected error
}

[ikatyang]

I think the only way to add a property to a function is using variable declaration, since you can't define a function type mixin with something else.

/** 
 * @type {{ (x: number): string, bar: number }}
 * @param {number} x
 * @return {number}
 **/
var foo2 = function (x) { return x };
foo2.bar = 1;

And for the @property tag, it seems TS only support with Object|object, see wiki.

@type: variable/property declaration
@property: @typedef {object or Object}
@param ,@return: function/method declaration

[OliverJAsh]

Thanks. I think your original conclusion was right. I can't find of any way to do this in .ts files with function declarations, other than converting to a function expression, so it makes sense that you can't do it with JSDoc too.