search

microsoft / tsdoc

A doc comment standard for TypeScript
https://tsdoc.org/
MIT License
4.7k stars 130 forks source link

param hyphen warning #316

Open chnliquan opened 2 years ago

chnliquan commented 2 years ago

the vscode use jsdoc to default IntelliSense, it will not generate hyphen minus in @param. if manually adding hyphen minus has a lot of cost, can you provide a configuration item to turn off the hyphen minus check

zelliott commented 2 years ago

This already exists I think - You can turn off tsdoc-param-tag-missing-hyphen in your api-extractor.json config file. Then you won't get warnings/errors for missing hyphens in @param tags.

https://github.com/microsoft/tsdoc/blob/e66ec2ca2fe453d53bae9bfe6fc62de7e4c2aef4/tsdoc/src/parser/TSDocMessageId.ts#L161

4Tel-SteveM commented 1 year ago

I would love to see a solution for the hyphen warning. I only intend to use the plugin for linting so the extractor solution is of no use. This issue is present in several issues without a solution being present. The hyphen rule issue is rather unfortunate as the default snippet in vsCode does not contain a hyphen so users will generally not insert one, making the plugin time-consuming to use.. I think the issue of configuring the rules is likely to limit the use of this plugin.

crystalfp commented 1 year ago

Maybe it is better to fix the snippet in VS Code. If the standard asks for it, then the warning IMHO should stay.

HarelM commented 1 year ago

I'm migrating a project from jsdocs to tsdocs. I have like 3000 missing hypen warnings. Is there a way to fix this using lint's --fix flag? If the only thing that is missing is the hypen it should be an easy fix, just like extra space at the end of the line rule...

HarelM commented 1 year ago

Also there's no way to disable a single rule, much like done with other lint tools. So if I have a warning I would like to suppress, I can't do it. I also am not using the api-extractor, instead I'm using dts-bundle-generator, which is a lot easier to setup... Currently all I can do is turn this off completely as I have like 1K warnings...

itssumitrai commented 5 months ago

Just stumbled upon the same. In a large codebase like ours where we have thousands upon thousands of jsdocs, its not very practical to add hyphens manually. Either there should be an option to configure it or a way to auto fix. Not very practical for large scale adoption.

octogonz commented 5 months ago

Just stumbled upon the same. In a large codebase like ours where we have thousands upon thousands of jsdocs, its not very practical to add hyphens manually. Either there should be an option to configure it or a way to auto fix. Not very practical for large scale adoption.

Probably the best approach would be a combination of:

  1. Provide a command similar to ESLint --fix that would automatically rewrite comments to use normalized TSDoc form
  2. Implement a VS Code extension that provides correct IntelliSense and previews for TSDoc comments. This would provide a generalized solution for all the issues where VS Code incorrectly parses TSDoc (because VS Code does not follow any formal syntax standard, it just makes a best guess based on commonly observed coding patterns)