phpDocumentor#40: Basic Implementation for Documentation Standards

In this commit I have added on the previous commit to create a
baseline way of dealign with Documentation Standard. phpDocumentor
now supports rulesets in the same way as PHP_CodeSniffer and as
such allows the custom creation of standards.

With this feature it will be possible to finetune and tweak how
your documentation is validated.

composer.json

@@ -7,7 +7,7 @@
     "autoload": {
         "psr-0":{
             "phpDocumentor": ["src/", "tests/unit/"],
-            "Cilex\\Provider": ["src/"]
+            "Cilex": ["src/"]
         }
     },
     "require": {

src/Cilex/CommandProviderInterface.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * phpDocumentor
+ *
+ * PHP Version 5.3
+ *
+ * @copyright 2010-2014 Mike van Riel / Naenius (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace Cilex;
+
+/**
+ * Describes a Service Provider that contains Commands.
+ *
+ * Because commands consume services when they are instantiated they should be registered after all services are
+ * registered with the container. By applying this interface and registering all commands inside the
+ * {@see self::registerCommands()} method Cilex will first register the services and after all services are registered
+ * register the commands.
+ */
+interface CommandProviderInterface
+{
+    /**
+     * Registers commands with the Container.
+     *
+     * @param Application $app
+     *
+     * @return void
+     */
+    public function registerCommands($app);
+} 

src/phpDocumentor/Application.php

@@ -12,9 +12,11 @@
 namespace phpDocumentor;
 
 use Cilex\Application as Cilex;
+use Cilex\CommandProviderInterface;
 use Cilex\Provider\JmsSerializerServiceProvider;
 use Cilex\Provider\MonologServiceProvider;
 use Cilex\Provider\ValidatorServiceProvider;
+use Cilex\ServiceProviderInterface;
 use Composer\Autoload\ClassLoader;
 use Monolog\ErrorHandler;
 use Monolog\Handler\NullHandler;
@@ -37,6 +39,9 @@ class Application extends Cilex
     /** @var string $VERSION represents the version of phpDocumentor as stored in /VERSION */
     public static $VERSION;
 
+    /** @var ServiceProviderInterface */
+    private $providers;
+
     /**
      * Initializes all components used by phpDocumentor.
      *
@@ -73,6 +78,37 @@ public function __construct($autoloader = null, array $values = array())
         $this->register(new Plugin\ServiceProvider());
 
         $this->addCommandsForProjectNamespace();
+        $this->registerCommands();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function register($provider, array $values = array())
+    {
+        $this->providers[] = $provider;
+
+        parent::register($provider, $values);
+    }
+
+    /**
+     * Scans all previously registered Service Providers and register any commands that they may expose.
+     *
+     * Commands generally consume services, which causes them to initialize. If we do this in the
+     * {@see self::register()} method then it might become impossible for other Service Providers to extend services
+     * that are already initialized.
+     *
+     * Using this method we delay the registration of Commands until all services are registered.
+     *
+     * @return void
+     */
+    public function registerCommands()
+    {
+        foreach ($this->providers as $provider) {
+            if ($provider instanceof CommandProviderInterface) {
+                $provider->registerCommands($this);
+            }
+        }
     }
 
     /**

src/phpDocumentor/Descriptor/ProjectDescriptorBuilder.php

@@ -17,8 +17,7 @@
 use phpDocumentor\Descriptor\Filter\Filterable;
 use phpDocumentor\Descriptor\ProjectDescriptor\Settings;
 use phpDocumentor\Descriptor\Validator\Error;
-use phpDocumentor\Descriptor\Validator\Rule;
-use phpDocumentor\Descriptor\Validator\Ruleset;
+use phpDocumentor\Plugin\Standards\Ruleset;
 use Psr\Log\LogLevel;
 use Symfony\Component\Validator\ConstraintViolation;
 use Symfony\Component\Validator\Validator;
@@ -46,23 +45,40 @@ class ProjectDescriptorBuilder
     /** @var Ruleset */
     private $ruleset;
 
+    /**
+     * Initializes this object and registers its dependencies.
+     *
+     * @param AssemblerFactory $assemblerFactory
+     * @param Filter           $filterManager
+     * @param Validator        $validator
+     */
     public function __construct(
         AssemblerFactory $assemblerFactory,
         Filter $filterManager,
-        Validator $validator,
-        Ruleset $ruleset
+        Validator $validator
     ) {
         $this->assemblerFactory = $assemblerFactory;
         $this->validator        = $validator;
         $this->filter           = $filterManager;
-        $this->ruleset          = $ruleset;
     }
 
+    /**
+     * Creates a new ProjectDescriptor with the default project name.
+     *
+     * @return void
+     */
     public function createProjectDescriptor()
     {
-        $this->project = new ProjectDescriptor(self::DEFAULT_PROJECT_NAME);
+        $this->setProjectDescriptor(new ProjectDescriptor(self::DEFAULT_PROJECT_NAME));
     }
 
+    /**
+     * Registers a project descriptor to build child Descriptors on.
+     *
+     * @param ProjectDescriptor $projectDescriptor
+     *
+     * @return void
+     */
     public function setProjectDescriptor(ProjectDescriptor $projectDescriptor)
     {
         $this->project = $projectDescriptor;
@@ -78,6 +94,20 @@ public function getProjectDescriptor()
         return $this->project;
     }
 
+    /**
+     * Registers a ruleset containing the validation rules that are to be applied.
+     *
+     * @param Ruleset $ruleset
+     *
+     * @see Ruleset for more information on what Rulesets are and what they do.
+     *
+     * @return void
+     */
+    public function setRuleset(Ruleset $ruleset)
+    {
+        $this->ruleset = $ruleset;
+    }
+
     /**
      * Verifies whether the given visibility is allowed to be included in the Descriptors.
      *
@@ -112,9 +142,17 @@ public function isVisibilityAllowed($visibility)
         return $this->getProjectDescriptor()->isVisibilityAllowed($visibility);
     }
 
-    public function buildFileUsingSourceData($data)
+    /**
+     * Accepts a value representing a File, tries to create a series of Descriptors matching the contents of that File
+     * and registers the assembled File Descriptor on the Project Descriptor.
+     *
+     * @param mixed $fileData Can be of any type as long as a FileDescriptor Assembler recognizes it.
+     *
+     * @return void
+     */
+    public function buildFileUsingSourceData($fileData)
     {
-        $descriptor = $this->buildDescriptor($data);
+        $descriptor = $this->buildDescriptor($fileData);
         if (!$descriptor) {
             return;
         }
@@ -197,10 +235,13 @@ public function validate($descriptor)
         foreach ($violations as $violation) {
             $message  = $violation->getMessageTemplate();
             $severity = LogLevel::ERROR;
-            $rule     = $this->ruleset->getRule($message);
-            if ($rule) {
-                $message  = $rule->getMessage();
-                $severity = $rule->getSeverityAsLogLevel();
+
+            if ($this->ruleset !== null) {
+                $rule = $this->ruleset->getRule($message);
+                if ($rule) {
+                    $message  = $rule->getMessage();
+                    $severity = $rule->getSeverityAsLogLevel();
+                }
             }
 
             $parameters = $violation->getMessageParameters()