The right way to document param of a param function

[KillyMXI]

Search terms

argument description, parameter description, parameter of an arrow function, lambda

Question

Previously (with version 0.23.x) I was using the following doc comment:

/**
 * ... irrelevant ...
 *
 * @param f - A function to produce a side effect...
 */
export function action (
  /**
   * @param data - Data object...
   * @param i - Position...
   */
  f: (data: Data, i: number) => void
): void;

Now (with 0.26.x) I noticed that data and i are left undescribed. Looks like I have to change how I document them:

/**
 * ... irrelevant ...
 *
 * @param f - A function to produce a side effect...
 */
export function action (
  f: (
    /** Data object... */
    data: Data,
    /** Position... */
    i: number
  ) => void
): void;

Was this a conscious change or an omission? I don't quite like how this looks in my code - harder to grasp. So, I wonder whether it is the idiomatic way to document args of the arg function.

---

Support in VSCode:

• @params show up when I hover over f in the implementation;
• directly applied doc strings can show up in certain situations (not very practical) in the client code.

The second example might be preferential for the client code, but the support is not ideal, so I don't see significant advantage there.

[Gerrit0]

I have no idea how that used to work in 0.23...

In your first example, the @param comment is overwriting the comment on the parameter itself, so TypeDoc doesn't have it when it checks for the @param comments for data and i... the following is roughly equivalent:

/**
 * ... irrelevant ...
 */
export function action (
  /**
   * A function to produce a side effect...
   * @param data - Data object...
   * @param i - Position...
   */
  f: (data: Data, i: number) => void
): void;

With this, the @param doesn't show up when hovering over the function anymore, but it does show up when filling out the parameter, and because the @param didn't overwrite the comment, TypeDoc can process the @param data and @param i tags.

This unfortunately doesn't quite work correctly in 0.26.6 because I forgot to check for @param comments within parameters, which I've just fixed.

---

Personally, I try to write code which doesn't need comments on parameters of callbacks... TypeDoc's "everything is documented" validation option actually explicitly excludes documenting parameters & properties of types on parameters of functions. If the type is complicated enough to need documentation there, it probably ought to be extracted to a type alias...

[KillyMXI]

Thank you.

Looking at what your suggestion produces currently with 0.26.6:

Does it fill (2) after the fix? Will it still keep (1) and is there a way to remove just it? I find (1) unnecessary.

[Gerrit0]

in 0.26.7 it will produce this: (I declared a dummy Data type)

[Contraboi]

Is this work in progress?

[Gerrit0]

4295105c484f98c9ef85386deac008c3ef866f73 fixed it, will be included in the next release as shown in the milestone. I plan to release that this weekend