[IntelliSense] [Salsa] Support @callback in JSDoc

[egamma]

From @santiagohdzb on March 15, 2016 3:43

Hi everyone, I'm in love with the new VS Code's Salsa, but I'm facing this issue:

I'm trying to use InselliSense with JSDoc's callback documentation.

Am I doing something wrong? How am I supposed to do this?

• VSCode Version: 0.10.11
• OS Version: Win 10

Steps to Reproduce:
1. Open a new Javascript file
2. add the code you see above

Copied from original issue: microsoft/vscode#4223

[egamma]

From @anseki on March 15, 2016 5:6

Hi @santiagohdzb,
Now, it seems that IntelliSense indicates some types other than primitive data type and Object as any.
Some types of JavaScript's built-in-object (e.g. Date, RegExp, etc.) are recognized, but some types (e.g. Array, Map, etc.) are not.
microsoft/vscode#3802

[egamma]

Moving to TypeScript for investigation.

[pisrael]

I'm having the same problem with JSCode. Any workaround?

[mhegazy]

We have recently added support for JSDOC @typedef. if you are using the nightly build, you can replace the pattern above with:

/**
 * @typedef {function(number)} addedCallback
 */

/**
 *@param {addedCallback} a
 */
var add = function (a) { 

}

[sant123]

@mhegazy is there a way to do this with TypeScript v1.8.10? Or only for the next release of TypeScript 2.0?

Thanks.

[zhengbli]

@sant123 support for @typedef is added only in 2.0, and won't be ported back to 1.8.10. You can use the nightly build via npm install typescript@next -g to use it today.

[sant123]

Thank you @zhengbli 😄

[CaptainOfFlyingDutchman]

Any progress on this?

[episage]

+1

[slawo]

+1
typedef is very limited and doesn't change anything compared to describing the callback inline:

/**
 *@param {function(int)} a
 */
var add = function (a) { 

}

The real use of @callbak is to properly describe all the parameters of the callback and sometimes the expected return value and its effect on the curent function.

[adalinesimonian]

Hate to be that person, but it's been 3 months since the last comment on this issue. Any updates, blocking issues? Is it backlogged, perhaps?

[mhegazy]

it is on our Future milestone. so no specific release has been marked. would be happy to take a PR for it anytime though.

[iugo]

@mhegazy How to name arg0, arg1 for function(number, string)?

[JobLeonard]

EDIT: Ignore what I wrote here, @mhegazy showed a much simpler method below.

EDIT2: maybe not quite ignore what I wrote here, it has a slightly different trade-off than the other method.

@iugo: the only one workaround right now is to create "dummy" functions, see this earlier comment by @slawo.

It's a bit crude, but as long as you use a bundler like WebPack, which can do dead code elimination, you shouldn't have to worry about those dummy functions it ending up in your production code.

Here's more elaborate example, extracted fron a bigger code snippet:

/**
 * A compare function to pass to `indices.sort()`, see also:
 * [`TypedArray.prototype.sort()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/sort).
 *
 * @param {number} i
 * @param {number} j
 */
function indexCompareFunction(i, j) {
  // dummy function for missing VSCode JSDoc callback support
  return i - j;
}

// Explicit
/**
 * Creates a compare function to sort a _separate_ array
 * of indices, based on lexicographical ordering of
 * the array values. Produces a stable sort.
 * @param {*[]} array
 * @returns {indexCompareFunction}
 */
function baseCompareFunc(array) {
  return (i, j) => {
    let vi = array[i],
      vj = array[j];
    return vi < vj ?
      -1 : vi > vj ?
        1 : i - j;
  };
}

// Inferred from callback JSDoc
/**
 * @param {*[]} array
 */
function baseCompareFunc2(array) {
  // Must store the function in a variable,
  // otherwise JSDoc does nothing!
  /**
   * @param {number} i
   * @param {number} j
   */
  let compareFunc = (i, j) => {
    let vi = array[i],
      vj = array[j];
    return vi < vj ?
      -1 : vi > vj ?
        1 : i - j;
  };
  return compareFunc;
}

[mhegazy]

@iugo: the only workaround right now is to create "dummy" functions, see this earlier comment by @slawo.

@JobLeonard this is not accurate. you can do this today using function, e.g.:

/**
 * Creates a compare function to sort a _separate_ array
 * of indices, based on lexicographical ordering of
 * the array values. Produces a stable sort.
 * @param {*[]} array
 * @returns {function(number, number): number}
 */
function baseCompareFunc(array) {
    return (i, j) => {
      let vi = array[i],
        vj = array[j];
      return vi < vj ?
        -1 : vi > vj ?
          1 : i - j;
    };
  }
  

[JobLeonard]

@mhegazy: I actually missed this option, so thanks!

However, the question was:

How to name arg0, arg1 for function(number, string)?

I don't see any other way to get named arguments in there at the moment, other than creating a dummy function.

(EDIT: Yes I'm using three-spaces indented tabs. I regret nothing)

[mhegazy]

How to name arg0, arg1 for function(number, string)?

/**
 * @param {*[]} array
 * @returns {{(i:number, j:number)=> number}}
 */

[JobLeonard]

Wow, nice! That {{ () => .. }} notation is new to me though, and skimming through the JSdoc pages doesn't give me any hints either - in fact a sitewide search gives just one hit, and it's not this.

[mhegazy]

inside { .. } we allow TypeScript type syntax, and that is how you define a call signature in TS.

[JobLeonard]

Ah, so it's technically not valid JSDoc syntax, and this will only work in VSCode?

I mean, that's perfectly fine by me, but it might be important to some.

[mhegazy]

yes. it is not standard JSDoc (thought is very hard to define what is a "standard" in JSDoc). We still have this issue open to support the @callback natively.

[amedley]

I too could really use the native JSDoc @callback syntax because not everyone I work with uses VSC (so we require native documentation). For now I am just setting all callback parameters in documentation to @param {function} callbackName so that when this is fixed I can easily go back and find all occurrences of @param {function} to tidy up documentation.

[MichaelMitchellM]

Hi, this is still a problem in 1.21.0-insiders.
Has any progress been make on this?

[Gochida]

yes. it is not standard JSDoc (thought is very hard to define what is a "standard" in JSDoc). We still have this issue open to support the @callback natively.

At least when I needed to find out how to define a callback in jsdoc, the path to doing it was very well laid out and @callback was the top result for "how to document callbacks in jsdoc". I'm not sure how more 'standard' it needs to be considered when usejsdoc.org lays out what @callback is and how it works - and is the top result in google searches. I think it'd be reasonable to assume @callback should work the way usejsdoc.org defines it.

@typedef is a poor substitute with no way to define argument names properly. I can either do it the way google is saying others do it and leave people using my code in VSCode high and dry, or incompletely document it the way VSCode allows and leave nothing for those using an IDE with more complete JSDoc support.

Neither seems like a happy solution to me. The purpose of good portable documentation is lost if only part of jsdoc is implemented. This issue has existed for 2 years now, how much longer is it going to take to support SOME kind of callback documentation in VSCode? Callbacks are a major part of JS AND TypeScript - not being able to have documentation half as good as you get in another IDE is silly at this point. Even more silly when VSCode is meant to be the defacto IDE for languages like TypeScript.

VSCode could come out with it's own special @VSCodeCallback if need be - as long as there's something, I could then define the callback twice - vscode's way, and the way everyone else does it - and no one is left with incomplete documentation about my callbacks then.

[TheLarkInn]

@DanielRosenwasser @mhegazy this would be pretty nice for us also since we are incredibly callback heavy.

[sandersn]

Fix is up at #23947