Rule documentation in metadata

[Arcanemagus]

ESLint defines a metadata property (meta.docs.url) for rules to specify a URL where the full documentation for the rule can be found.

One of your users recently submitted jfmengels/eslint-rule-documentation#35 to get documentation links showing in some places, but this should be being specified using the metadata property so anywhere that supports ESLint rules will know the proper link to the documentation.

Ideally while solving this you probably should move the documentation into a docs/rule-name.md structure to allow for greater detail for each rule (and cleaner links), but that isn't a requirement 😉.

Note: This was originally filed as #1, but I believe that may have been before ESLint added the metadata property.

[evilpacket]

This sounds like a good idea and something I wasn't aware of. We can likely just have docs in the github repo and then point to them correct?

[Arcanemagus]

Yep! A common tactic is to generate the URL to point to the specific release tag of the version the user is running, so if the documentation has changed at a later point as the rule updates they aren't seeing conflicting information.

If I were to implement it currently I would use something like this:

import { basename } from 'path';
const pkg = require('../../package');

const repoUrl = 'https://github.com/nodesecurity/eslint-plugin-security';

/**
 * Return the URL of the rule's documentation, either from parameter or the
 * requiring file's name.
 * @param  {String} ruleName   The name of the rule to generate a URL for.
 *                             Defaults to the name of the calling file.
 * @param  {String} commitHash Hash of a specific ommit or tag name, defaults
 *                             to the current package version.
 * @return {String}            The URL of the rule's documentation.
 */
const getDocsUrl = (ruleName, commitHash) => {
  ruleName = ruleName || path.basename(module.parent.filename, '.js');
  commitHash = commitHash || `v${pkg.version}`;
  return `${repoUrl}/blob/${commitHash}/docs/rules/${ruleName}.md`;
};

That's a combination of functionality from a few different previous PR's where I implemented this, you can check these for further examples on how to use the above function 😉:
avajs/eslint-plugin-ava#184
jfmengels/eslint-plugin-lodash-fp#59

[jesusprubio]

Summary
It would be convenient for our users and external tools to include more rule documentation in the ESLint metadata property.

Still relevant?
Yes.

Next steps

• Decide the format to add extra info to a rule.
  • Related: Add ESLint meta object with description and category #61
  • Is it going to be mandatory for every rule?
• Update actual rules based on the decision

[MarkKragerup]

I propose a simplified PR compared to #61 which adds only meta descriptions, and doesn't modify code with unused variables etc. It should be conflictless. I will look into a PR draft.

[MarkKragerup]

I made a PR to replace #61. The differences are outlined in the description: #79