vim-doge icon indicating copy to clipboard operation
vim-doge copied to clipboard

Published 20 hours ago • verified publisher icon kkoomen

Avoid type redundancy in TypeScript

Open resolritter opened this issue 5 years ago • 3 comments

Is your feature request related to a problem? Please describe.

When generating documentation with JSDoc for TypeScript, it's redundant to add the type to the comments because they are already specified in the functions' signatures. In the editor, the IDE integration tells us so:

image

Aside from redundancy, another issue is that if we change the function's types, the JSDoc will be outdated with the old types.

Describe the solution you'd like

One of two solutions:

  1. If we omit the types in JSDoc, this is no longer an issue and the warning goes away. I think I prefer this because TSDoc is still a work-in-progress and the spec is not fully mature yet, it seems.

  2. The alternative, TSDoc, does not include the types into the comments. However, the spec is under discussion and it will surely be constantly changing in the near future, so I think it's not the time to add support for it. https://github.com/microsoft/tsdoc

Describe alternatives you've considered

Manually removing each type from the comments isn't good.

resolritter avatar Dec 04 '19 12:12 resolritter

I do agree with the redundancy. For me it would be more logical to add the type if the type is not listed in the parameter itself, otherwise we can remove it. Would that be an idea?

Regarding the TSDoc, love to support it but as you said, it's heavily discussed so it's better to wait for a while now.

kkoomen avatar Dec 04 '19 16:12 kkoomen

Your idea is even better than what I was imagining @kkoomen !

If it's not too much trouble, you could omit those type annotations only through a configuration variable, leaving the default as it is currently. That warning is coming from tsserver and some people might not have it enabled, so it's maybe not an issue for them.

I thought of hiding that specific warning only on my end, but I believe tsserver is what's used for VSCode and other IDEs too; everyone using it might benefit from the change.

resolritter avatar Dec 04 '19 17:12 resolritter

If it's not too much trouble, you could omit those type annotations only through a configuration variable, leaving the default as it is currently.

I think I should. Some prefer it, some don't.

Since we're doing quite a big rewrite at the moment (see #65) all features will be done after #65 has been merged.

kkoomen avatar Dec 06 '19 02:12 kkoomen