How do I properly document the type of functions passed as arguments, without extracting them to another type?

[Annoiiyed]

Hi! To clarify the title, the following code:

/**
 *
 * Adds equality functions to a data object. This freezes an object.
 * HashCode is lazily evaluated and memoized.
 *
 * @param <D> The type of the data object
 * @param data The data object to add equality to
 * @param equals The equality function
 * @param hashCode The hash code function
 *
 * @returns The data object with equality added
 */
export default function <D extends Record<string, unknown>>(
  data: D,
  equals: (a: D, b: D) => boolean,
  hashCode: (data: D) => number
): D & HasEquals {
    // ....
}

Needs @param hashCode.__type and @param equals.__type, else validation will show the following:

./src/lib/utils/addEquality.ts:20:10 - warning addEquality.equals.__type does not have any documentation.
20      equals: (a: D, b: D) => boolean,

./src/lib/utils/addEquality.ts:21:12 - warning addEquality.hashCode.__type does not have any documentation.
21      hashCode: (data: D) => number

[Gerrit0]

This looks like a bug in the validation, it should accept the comment on the parameter reflection as the comment.

[Gerrit0]

Hmm... on second review, I guess it's technically correct that the a parameter of equals isn't documented. I don't think it makes sense to complain about this. You could add an inline comment for this parameter, but I think I'm going to update the validation to ignore parameters within parameters...

export default function <D extends Record<string, unknown>>(
  data: D,
  equals: (/** Inline docs */a: D, b: D) => boolean,
  hashCode: (data: D) => number
): D & HasEquals {
    // ....
}

or

export default function <D extends Record<string, unknown>>(
  data: D,
  /** Inline docs with @param a */
  equals: (a: D, b: D) => boolean,
  hashCode: (data: D) => number
): D & HasEquals {
    // ....
}