Support for documenting params with named types

[Leo-Nicolle]

Search Terms

@params params named types function

Problem

When documenting functions, it happens that params use named types. If this type is used only once in the while code, it is fine, but if this type is reused multiple times, it would be handy to document it within the function using it:

/**
 * Docs on the options Type 
 * @property a - Nice ! But there would be cases when it is not enough
 * @property b - If the type is reused, then defaultValues would be wrong, for instance
 */
type MyOptions ={
  a: number;
  b: string;
};
/**
 * A function using named options
 * @param options Okay this comment is picked up
 * @param options.a This is absent
 * @param options.b This is absent too
 */
function fn1(options: MyOptions){
  return options
}
/**
 * A function using unnamed options
 * @param options Okay this comment is picked up
 * @param options.a With unnamed types it works
 * @param options.b With unnamed types it works
 */
function fn2(options: {a: number, b: string}){
  return options
}

export {fn1, fn2, MyOptions};

Here the comments for fn1 wont be picked up, nor in HTML or JSON output.

Suggested Solution

Include all the @params tags within the function comments in the result JSON.

I did not try to clone the code yet and run it, but it seems to me that somewhere around here we look for comments which have @param paranName comment with paramName matching the name in the code. I guess we could return all comments which start by paranName. . And then it would be for the users to implement their own way of dealing with it while processing the JSON output.

I have attached a little example project (with the same code I pasted up in the issue, and commands etc) tsdoc-param-functions.zip

What do you think ?

[Gerrit0]

Copying this in from #2456:

Duplicate of #2147, which apparently I never pressed comment on my response to...

TypeDoc doesn't do this today as parameter display is tied to the type display. There's a proposed fix for the linked issue which I don't much like because it essentially hacks around this by adding extra @param tags on the parameter.

It also needs more design consideration for edge cases:

• What happens if you specify a property that doesn't exist on the linked type? What if there's an index signature on the linked type?

• What happens if you don't specify every property on the linked type?

• What happens if the linked type doesn't actually exist as far as TypeDoc is concerned? (Marked with @ignore, present in some declaration file that's excluded with --excludeExternals)

• What if the linked type isn't an object? What if it's an intersection of objects? A union?

[13BTurbo]

I have come across this too. Any update?

I get warnings (similar to #2483): [warning] The signature hooks/use-websocket-events.useWebSocketEvents has an @param with name "props.onlineCallback", which was not used.

/**
 * A hook to trigger callbacks on WebSocket API state changes.
 * @param props The hook's callback props
 * @param props.onlineCallback Called when the websocket service is done syncing with the controller.
 * @param props.offlineCallback Called when the websocket is disconnected.
 * @param props.connectCallback Called when the websocket is connected.
 */
export function useWebSocketEvents({
  onlineCallback,
  offlineCallback,
  connectCallback,
}: UseWebSocketEventsProps): void {

Granted the output provides a link to the interface and the interface is documented, however VSCode with eslint-plugin-jsdoc issues warnings if the destructured @param parameter.property style tags are missing, so I'm stuck with warnings in VSCode or Typedoc either way. Perhaps an option to suppress these warnings when there is a link to the interface is enough?

[13BTurbo]

Just switched from eslint-plugin-jsdoc to eslint-plugin-tsdoc and now I can remove the @param parameter.property style tags and VSCode no longer issues warnings.

[JulianWowra]

What do you think about the integration of this feature after the current release, @Gerrit0 ?

[Gerrit0]

It is still planned to happen at some point, that's why the issue is still open.