document plugin capabilities (closes #5262)

doc/articles/plugins.md

@@ -183,6 +183,76 @@ class AwsPlugin implements PluginInterface, EventSubscriberInterface
 }
 ```
 
+
+## Plugin capabilities
+
+Composer defines a standard set of capabilities which may be implemented by plugins
+through the [`Composer\Plugin\Capable`][8] interface.
+
+### Command provider
+
+The [`Composer\Plugin\Capability\CommandProvider`][9] capability allows to register
+additional commands for Composer :
+
+```php
+<?php
+
+namespace My\Composer;
+
+use Composer\Plugin\Capability\CommandProvider as CommandProviderCapability;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Composer\Command\BaseCommand;
+
+class CommandProvider implements CommandProviderCapability
+{
+    public function getCommands()
+    {
+        return array(new Command);
+    }
+}
+
+class Command extends BaseCommand
+{
+    protected function configure()
+    {
+        $this->setName('custom-plugin-command');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        $output->writeln('Executing');
+    }
+}
+```
+
+Once the plugin exposes this capability, `custom-plugin-command` is
+available alongside Composer commands :
+
+```php
+<?php
+
+namespace My\Composer;
+
+use Composer\Composer;
+use Composer\IO\IOInterface;
+use Composer\Plugin\PluginInterface;
+
+class Plugin implements PluginInterface
+{
+    public function activate(Composer $composer, IOInterface $io)
+    {
+    }
+
+    public function getCapabilities()
+    {
+        return array(
+            'Composer\Plugin\Capability\CommandProvider' => 'My\Composer\CommandProvider',
+        );
+    }
+}
+```
+
 ## Using Plugins
 
 Plugin packages are automatically loaded as soon as they are installed and will
@@ -202,3 +272,5 @@ local project plugins are loaded.
 [5]: https://github.com/composer/composer/blob/master/src/Composer/IO/IOInterface.php
 [6]: https://github.com/composer/composer/blob/master/src/Composer/EventDispatcher/EventSubscriberInterface.php
 [7]: ../01-basic-usage.md#package-versions
+[8]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capable.php
+[9]: https://github.com/composer/composer/blob/master/src/Composer/Plugin/Capability/CommandProvider.php