Docs: per-rule docs (eslint-doc-generator)?

[JoshuaKGoldberg]

👋 I was just pointed to this plugin by @atilafassina - and it's great, thank you for making it! +1 to having some system to enforce good react-refresh usages.

But, I found it hard to learn about this plugin and rule. There's no explicit listing of the rule(s) it comes with and so I had to peek into the src/ directory.

Most ESLint plugins today either have their own website (e.g. https://perfectionist.dev) or use eslint-doc-generator to create docs and keep them up-to-date. The latter is what most projects do that don't have a huge amount of options, rules, etc.

Would you be open to using eslint-doc-generator to align the docs to other plugins? Or failing that, having docs similar to it?

[ArnaudBarre]

Yeah some people pointed out the lack of documentation.

For now the plugin is a only one rule, and I wanted to keep it simple as I don't see any rule that could be added to it. So a website feels like a lot, and a tool to sync the only rule with the readme too. For the same reason I didn't want to make a configuration.

Maybe we can improve the readme making it explicit this is a 1 rule plugin? I'm open to improvements on the readme for sure.

From my point of view, what is lacking is a good way to explain the what and why of the plugin/rule for people that don't know Fast Refresh. I've read almost all the internals of it, so I my explanations always overwhelming for others (some people can, but I'm not good at it!). Ideally this should be documented on the new official React doc. It's been on the docs of React Native, Next, ... but not "officially" documented by the React team.

What I would also love to add is typing information for people building config to avoid typos in the name/options. I didn't found anything that was able to type options and don't make users that don't use typed config download megabytes of types. If you have a suggestion I'm happy to improve this.

[JoshuaKGoldberg]

Cool, thanks! I suppose this is really a somewhat-duplicate-ish of #28 then. Sent #63 to generally make the docs clear per these two issues.

What I would also love to add is typing information for people building config to avoid typos in the name/options. I didn't found anything that was able to type options and don't make users that don't use typed config download megabytes of types. If you have a suggestion I'm happy to improve this.

That's a great question. I don't know the right answer that doesn't involve a dependency on something from @typescript-eslint/*.

Personally, I use @typescript-eslint/utils per typescript-eslint's Custom Rules. Per https://pkg-size.dev/@typescript-eslint%2Futils, if you exclude peer dependencies such as typescript, it's a total of 4.4MB. Once JoshuaKGoldberg/ts-api-utils#573 is fixed it'll still be above 3MB. 😬. I filed typescript-eslint/typescript-eslint#10383 to suggest making a standalone package that omits other dependencies of @typescript-eslint/utils.

Otherwise, I don't know of a standard standalone thing for this. https://github.com/azat-io/eslint-plugin-perfectionist/blob/main/index.ts is a really nice reference for how you could do it on your own, without a full dependency on any @typescript-eslint/* stuff (h/t @azat-io).