New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
How to enforce docs on Typescript interface and its properties using EsLint? #209
Comments
Not yet, but we've been wanting to make one! Want to propose a design? |
@micthiesen brought up the same question in #228. The first step is to agree on a design: How would the rule work? (Does it check every class/member/function? Only exported ones? Only ones marked as What options would it support? (Is there a minimum number of words required in the documentation? Is there a way to "opt-out" for a given item?) Maybe we could base the design on an existing ruleset like eslint-plugin-jsdoc. But if we do that, which subset of features should we start with? |
@octogonz If basing off of eslint-plugin-jsdoc rules, it looks like require-description and require-jsdoc would be two generic rules to start with that would satisfy #228 and would lead to further rules for solving #209. Starting with |
Sure, although I think the more interesting design question is around which things need comments. Fantasizing for a moment, in our own projects, I think I'd like a policy such as:
This may seem lax, but it's based on a philosophy that it's bad to write documentation that doesn't convey any new information. For example if the lint rule makes people write something like this... /** Stores a width and height. */
interface ISize {
/** The width component of the size. */
width: number;
/** The height component of the size. */
height: number;
} ...it doesn't just waste screen space, it normalizes an attitude that documentation is an empty formalism, jumping-through-the-hoops to appear like we have have documentation, rather than being about trying to communicate non-obvious information that helps developers understand and use your APIs. Does that seem reasonable? If so we could take something like this as the goal, and maybe we can then start by implementing a meaningful subset of it. @arenglish are you interested to contribute a PR? |
I completely agree with that and know that many values like variables and class members can usually be reasonably documented just with just an appropriate name. I'm very new to tsdoc, I just came across it while searching for a good in-code documenting system for our angular monorepo, and found Compodoc and Typedoc, both of which seem to be implementing something similar to tsdoc except that it's based on jsdoc. I would definitely be interested in contributing a PR for this, but I'm going to pull down the code base and get familiar with the API Extractor so I can have more context before starting. I think all the policy points you listed are a solid starting point. In our case, class constructors can sometimes get complex making docs on constructors that require arguments a potential need, but I'll think through the different use cases we have over the next few days to compare with the ones you've come up with. |
Seems reasonable. By the way, we generally solve this by avoiding anonymous types. Instead of this: class Vector {
// anonymous type literal
constructor(options: { width: number; height: number; }) { }
} ...we would always write it like this: interface IVectorOptions {
width: number;
height: number;
}
class Vector {
// named API
constructor(options: IVectorOptions) { }
} Thus the documentation requirements for |
Such a rule would be highly desirable. |
tsdoc looks very promising but not having 'require' rules is a show stopper for me https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-jsdoc |
I also want to enforce TSDocs. I more or less agree with @octogonz’ comment, but I think the users need to have a way to disable individual top-level declaration types ( I wish this would be implemented ASAP. Unfortunately, I am not that good coder, so I can’t help you implementing it. |
breaking lint plugins to individual rules probably provides that ability. doesn't it? |
Any updates on this? Really wanting to use tsdoc but as @bigman73 mentioned this is also a show stopper for me. |
Let me push this. We really need this feature in our dev team. Any updates? Or does anyone know an alternative eslint docs plugin that works with typescript and has this feature? |
I ended up looking at tsdoc as I observed that our codebase lacked documentation and I was hoping that this will at least allow us to force people to write some documentation but now I see that this plugin can check the format of the docs but not the absence of the docstrings... bit confused as that would have being the first feature I would have implemented. |
Opened since 2020. Any news on that? Or is the plugin dead? |
So, for those who are still waiting for MS to move, I started implementing a new eslint plugin to enforce the usage of TSDoc comments on exported types. There is a preview version that checks the high level types (not the public members of classes and interfaces yet). It is not published on npm, but you can install it directly from github:
Comments, suggestions and contributions are welcome. |
Although this rule is deprecated, it works in our codebase to force tsdoc: |
Solved it by using // .eslintrc.js
// ...
"jsdoc/require-jsdoc": [
"error",
{
publicOnly: {
cjs: true,
esm: true,
window: true,
},
require: {
ArrowFunctionExpression: true,
ClassDeclaration: true,
ClassExpression: true,
FunctionDeclaration: true,
FunctionExpression: true,
MethodDefinition: true,
},
contexts: [
"TSInterfaceDeclaration",
"TSTypeAliasDeclaration",
"TSEnumDeclaration",
"TSPropertySignature",
],
},
],
// ... |
I am looking to enforce documentation on the interfaces and all of its properties using eslint. I have installed
eslint-plugin-tsdoc
package in my project. Is there a rule to enforce it?Thanks
The text was updated successfully, but these errors were encountered: