[sarahdellysse]

So say we had code like this:

  const safeSplice = (items, start, deleteCount, ...itemsToAdd) => {
    const copy = [...items];
    const deleted = copy.splice(start, deleteCount, ...itemsToAdd);
    return {
      deleted,
      list: copy,
    };
  };

We could put this as a jsdoc-style typescript comment just before the `const safeSplice` line:

  /** @type {<Item>(items: Array<Item>, start: number, deleteCount?: number, itemsToAdd?: Array<Item>) => { deleted: Array<Item>, list: Array<Item> }} */

or as a multi-line type declaration:

  /** @type {<Item>(
    *   items: Array<Item>,
    *   start: number,
    *   deleteCount?: number,
    *   itemsToAdd?: Array<Item>
    * ) => {
    *   deleted: Array<Item>,
    *   list: Array<Item>
    * }}
    */

Alternatively, you could do something like this in place of the above:

  /*
   * @template Item
   * @param {Array<Item>} items
   * @param {number} start
   * @param {number} [deleteCount]
   * @param {Array<Item>} itemsToAdd
   */

I started out doing the former because I liked using the typescript notation, but I ended up doing the latter more often as I could leave the return type off the signature, which I prefer to do

[FractalHQ]

This is really cool! TIL. At this point though, I feel like you might as well just use Typescript, no? You’ll get more features / tooling and cleaner syntax. I’m intrigued to learn more about advanced JSDoc now though, if anything to be more prepared if I’m ever forced to work with it in the future.