search

dusk-network / eslint-config

⚙️ Dusk ESLint configuration
Mozilla Public License 2.0
3 stars 12 forks source link

Add eslint-plugin-jsdoc for improving documentation #13

Open kieranhall opened 10 months ago

kieranhall commented 10 months ago

By adding eslint-plugin-jsdoc we can have more confidence in the quality of the documentation of our code.

ascartabelli commented 10 months ago

We already used it in our toy repo, and I think it's a good fit for libraries, but I don't think it's worth it in an app, unless you restrict it to some parts of the $lib folder.

So I see two scenarios:

  1. we keep it only for external libraries -> we can leave its rules in our monorepo of libraries (as we did in the toy repo above)
  2. we add an optional config here that we can import where necessary in subfolders of an app (this will need adding extra eslint config files around, maybe we should wait for #12 as it seems like a big change?
kieranhall commented 10 months ago

Why would you not want to only use these rules outside of the $lib? I think that having JSDoc comments with useful descriptions can be useful in all components. We might not generate a HTML documentation from these comments (although, it could be interesting to see what that would look like), but structured comments like these with good descriptions can make for much more maintainable code.

ascartabelli commented 10 months ago

Why would you not want to only use these rules outside of the $lib? I think that having JSDoc comments with useful descriptions can be useful in all components. We might not generate a HTML documentation from these comments (although, it could be interesting to see what that would look like), but structured comments like these with good descriptions can make for much more maintainable code.

Oh, no, I explained myself badly. It's not that I don't want it, it's that I think that they are often unnecessary and (reusable) components are often better off with a storybook. But, you're right, if we're going to release open source code we should be more thorough anyway.

In the case of components it'll be also a bit harder to have proper JSDoc (as in comments with the purpose of generating HTML documentation).

kieranhall commented 10 months ago

I think it could be nice for us to, for example, have a less strict linting policy for JSDoc, but then have the option to, in the future, make these more strict. This way, we can always identify and enforce something we later consider important and have an easy refactoring for all the projects using this eslint config version.