Improve documentation "Working with Plugins"

[lorenzleutgeb]

I would like to write a plugin for commitlint.

Currently, the Working with Plugins page shows the following example:

module.exports = {
    rules: {
        "dollar-sign": function(parsed, when, value) {
          // rule implementation ...
        }
    }
};

The problem is that this just leaves me puzzling what values parsed, when and value will take at runtime. There's no single word on the semantics of a plugin, what a "rule implementation" is, and so forth.

Please describe the interface better, by stating the contract of the sketched function. Explain what the three parameters are used for, and equally important, what the function should return and how the return value is interpreted.

In addition to that, provide an example plugin. For example, fill out the body of the function above by checking that there is at least one dollar symbol in the header of the commit message and that at least two lines of the body of the commit message start with a dollar. Of course this is a totally made-up example, but it would show how to interpret the parameters.

[escapedcat]

Hey @lorenzleutgeb, yes, you are right. We need to update and improve the docs for plugins. It's on our list. Not sure when we'll find time.