Closed KillyMXI closed 1 week ago
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...
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.
in 0.26.7 it will produce this: (I declared a dummy Data
type)
Is this work in progress?
4295105c484f98c9ef85386deac008c3ef866f73 fixed it, will be included in the next release as shown in the milestone. I plan to release that this weekend
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:
Now (with 0.26.x) I noticed that
data
andi
are left undescribed. Looks like I have to change how I document them: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:
@param
s show up when I hover overf
in the implementation;The second example might be preferential for the client code, but the support is not ideal, so I don't see significant advantage there.