🛠️ Repo: Add eslint-plugin-compat or an equivalent

[boneskull]

I identified a use case for a custom JSDoc tag in our source.

Let's tag code that exists for the sole purpose of supporting a particular environment. Then, if/when we drop support for that environment, we can easily find what can be culled. Maybe @env?

Example, from lib/utils.js:

/**
 * `process.emitWarning` or a polyfill
 * @env IE11
 */
var doDeprecationWarning = process.emitWarning
  ? function(msg) {
      // Node.js v6+
      process.emitWarning(msg, 'DeprecationWarning');
    }
  : function(msg) {
      // Everything else
      process.nextTick(function() {
        console.warn(msg);
      });
    };

cc @craigtaub @plroebuck for feedback?

[craigtaub]

Sounds like a good idea. Should be 1 tag per env, no comma separation.

While we are on the subject think we could do with mandating how to use the tags. Im still not clear on whether to optimise for user access or module documentation.

[plroebuck]

I hate our API documentation now... Have been looking into possibility of restoring @api tag with custom jsdoc plugin (so it actually means something) and maybe we color methods with that tag differently to imply availability to user code.

[boneskull]

@plroebuck

Not only is it information overload, I can't see any reason consumers would need to know about APIs that aren't intended to be used. If you, the developer, want to see this documentation, it's easy to generate locally:

$ node_modules/.bin/jsdoc -c jsdoc.conf.js --private

...and you'll have everything in docs/_dist/api. We could also add something in package-scripts.js to do this.

[JoshuaKGoldberg]

This exists in https://github.com/amilajack/eslint-plugin-compat actually.