Tsdoc: TSLint rules to enforce TypeDoc?

[AndrewCraswell]

I'm having trouble finding if this exists... I know there are TSLint rules to enforce JSDoc comments, which is what I am using now. Wondering if there are any plans to have a similar rule to enforce complete TSDoc annotations. Also not sure if this question belongs here or in the TSLint repo, but thought the contributors here might have a better idea.

[aciccarello]

TSDoc will have a strict mode that will enforce a certain structure with white listed tags. However, I don't know if there is plans to require complete documentation.

[octogonz]

@AndrewCraswell could you post a link to the source code for the tslint rule you're using? I'd like to see how far they went with it.

Your idea makes sense to me. For example if you use API Extractor it does TSDoc validation, but only for exported public types. Might be useful to apply the checking more broadly, and tslint I think is a better way to do that. But it would maybe need access to the custom TSDoc configuration used by a project.

[AndrewCraswell]

Here is the link to the completed-docs rule in TSLint:
https://github.com/palantir/tslint/tree/master/src/rules/completed-docs

[AndrewCraswell]

My big thing is that I'd love to switch over to TSDoc, where we've been using JSDoc or nothing before. It helps junior engineers with the learning curve if they can at least see a list of warnings when something is missed. It really eases the burden of learning, and switches to a "learning in the flow of work" methodology.

[octogonz]

Their parser is in parseTagsWithContents(). It is really minimal, and basically just uses a regular expression to check whether specific tags appear in the comment. The rule itself has a ton of configuration options for specifying which language constructs the rule should apply to. Maybe we could propose for this rule to have an option that runs the TSDoc parser to validate the comment, instead of using the regular expression.

We haven't really done much activism yet towards encouraging other projects to adopt TSDoc. I wanted to write up the formal spec first, now that the parser is mostly complete. But if your feature is being proposed as opt-in switch for the rule, that's pretty low risk. They might go for it.

Or, if people think tslint+TSDoc is a good idea, maybe we could also consider instead setting up a dedicated @microsoft/tsdoc-tslint-rules package in our own repo. I don't have much time for that right now, but if the community wanted to contribute it, I'd support it.

[DylanVann]

Could possibly go into @typescript-eslint/eslint-plugin.

[octogonz]

Ironically this week I have been working in converting this repo to use ESLint. 😁 Thanks for bumping this issue.