Enforcement exclusions

[samhh]

Currently a rule such as enforceExamples is enforced against everything indiscriminately. This poses a challenge if I want to enable it in a repo like fp-ts where there's for example an index module. It also means I can't enable it for all new code in a repo going forward from any given point whilst ignoring the preexisting failures, as one might do for a linter or an upgrade from plain JS to TS.

In an ideal world docs-ts would allow you to specify exclusions or otherwise ignore certain files or pieces of code.

[gillchristian]

In an ideal world docs-ts would allow you to specify exclusions or otherwise ignore certain files or pieces of code.

How do you think this discriminated enforce could be implemented? And allow/exclude list of globs? Or a directive per export?

There's @ignore, for specific exports. But that ignores the whole thing not just the required example.

The index example from fp-ts you mentioned could be handle by ignoring the file directly. But again, that ignores the whole thing.

One thing I should ask is, is the complexity this would introduce worth the control we gain?

[samhh]

For the reasons I've posed I believe it would be, else the enforcement isn't practicable. It's the same reason linters et al always have opt-out directives.

As for implementation, as an end user, I don't really mind.

[gillchristian]

It's the same reason linters et al always have opt-out directives.

Makes sense!

As for implementation, as an end user, I don't really mind.

Sorry, I explained my self poorly. I didn't mean the internal implementation of the feature but what do you suggest in terms of how to opt-out of the enforced examples.

I think it could be inline directives to opt-out of the enforced examples for specific imports or a list in the configuration to enforce/opt-out on files.

We might want to do both, or at least a directive that allows opt-out for a whole file. Otherwise the index example you mentioned would require every single export to have the opt-out directive.

[samhh]

Ideally I'd be able to granularly ignore on a line-by-line basis a la eslint-disable[-next]-line as I have a few exports that don't need examples e.g. newtypes. I'd suggest that's the best place to start as that's the most flexible approach. Something like docs-ts-ignore-next-export example, version.

Certainly file-level directives would be nice as well a la eslint-disable.

I've mentioned ESLint a lot as it's what I use most regularly. Not sure how other ecosystems handle this.