@pgonzal and I were talking in an email thread about parsing params in api-extractor/tsdoc, and suggested I log an issue here to track the param parsing concerns.

Goals for param parsing should be;

1. Public exported classes/functions have correct jsdoc comments describing the thing.
2. If param comments are missing, api-extractor catches them and throws an error.
3. If params are out of order, also worthy of throwing an error.
4. If the params have types in them, api-extractor ignores them and parses the types from typescript typings if available.
5. If the params have dashes in them, api-extractor ignores the dashes. If they are missing dashes, api-extractor ignores that. (The purpose is to extract the docs and api surface, not be nit picky about unimportant things, especially when VSCode jsdoc formatting defaults to having types AND no dashes.)

Examples that should work:

  /**
   * @param foo This is fine.
   * @param foo {boolean} This is fine.
   * @param foo - This is fine.
   * @param foo {boolean} - This is fine.
   * @param foo - {boolean} This is fine.
   */

It is nice to stay consistent with param documentation, but the tools should also be resilient in the parsing and let formatting cleanup be the duty of tools like Prettier.

There might be a strict mode which enforces the VSCode default jsdoc comments. but please do not deviate from what most other open source projects snap to (the second example above.)

See Airbnb specs for their guidance as an example. Look at React jsdoc comments. etc

https://github.com/airbnb/javascript#comments