Proposal: Add URL for a rule's documentation to the API

The version of ESLint you are using.

4.12.1

The problem you want to solve

AtomLinter has a neat feature that links to the documentation for each rule.

In order for that link to work in plugins, the plugin needs to be registered in AtomLinter.

Your take on the correct solution to problem

Instead of AtomLinter having to maintain a list of known plugins (and other clients having to duplicate the effort) it would be great if the API could allow a rule to specify where its documentation can be found.

It boils down to:

1. Exposing a rule’s meta object via the API (which is a one-liner though several test fixtures are affected).
2. Establishing an optional convention of putting the URL describing a rule in docs.uri / docs.url.
3. Adding a URL to the meta for each of the built-in rules.

Original proposal which worked at the plugin level rather than the rule level.

module.exports = {
    rules: {
        ...
    },
    ...

    // New property
    getDocURI: function (ruleName) { 
       return `https://myplugin.com/docs/${ruleName}.md`
    }
};

The URL would be exposed to the Node API via the response from the verify() method.

{
    fatal: false,
    ruleId: "semi",
    severity: 2,
    line: 1,
    column: 23,
    message: "Expected a semicolon.",
    fix: {
        range: [1, 15],
        text: ";"
    },
    docURI:  "http://eslint.org/docs/rules/semi" // <-- New property
}

I’ve implemented the change in ESLint. I’m waiting for the proposal to be accepted so I can open a PR. If it’s accepted I’m happy to do the corresponding update for AtomLinter as well.

[platinumazure]

Okay, I commented on this long ago and then never followed up- sorry.

I’m 👍 to using a property in rule metadata for this. If someone wanted to expose URLs in the plugin definition file, they could do so by requiring the rule and getting the URI from its metadata. So I withdraw any objection I might have raised earlier.

I think TSC needs to review a proposal before this can be accepted. I could write up a summary in a day or two, but if someone beats me to it, all the better.

[ilyavolodin]

Meta object has been added to all core rules. We also now have API to retrieve metadata (and rules). I still think it would be nice to add metadata to the report object. So that would be the last thing that would need to be added. I can champion this proposal.