Misc fixes - PhpDocs mostly (#265)

* Misc fixes.
Fixed some PHPDocs.
Removed unnecessary returns.
Fixed typos.

src/Analysis/Debugger.php

@@ -231,7 +231,8 @@ protected static function _findPos($file, $callLine)
      * @param  array $pattern    The regexp to match on.
      * @param  array $backtrace  The backtrace.
      * @param  array $depth      Number of traces to keep.
-     * @param  array $maxLookup  The maximum lookup window.
+     * @param  int   $maxLookup  The maximum lookup window.
+     *
      * @return array             A cleaned backtrace.
      *
      */

src/Cli/CommandLine.php

@@ -52,8 +52,8 @@ public function options()
     /**
      * Gets/Sets/Overrides an option's attributes.
      *
-     * @param  string $name   The name of the option.
-     * @param  array  $config The option attributes to set.
+     * @param  string       $name   The name of the option.
+     * @param  array|string $config The option attributes to set.
      * @return array
      */
     public function option($name = null, $config = [], $value = null)

src/Cli/Kahlan.php

@@ -198,11 +198,9 @@ public function loadConfig($argv = [])
             $this->_commandLine->parse($argv, false);
 
             if ($commandLine->get('help')) {
-                return $this->_help();
-            }
-
-            if ($commandLine->get('version')) {
-                return $this->_version();
+                $this->_help();
+            } elseif ($commandLine->get('version')) {
+                $this->_version();
             }
         }
 
@@ -829,7 +827,7 @@ function waitsFor($actual, $timeout = null)
             function skipIf($condition)
             {
                 $current = Specification::current() ?: Suite::current();
-                return $current->skipIf($condition);
+                $current->skipIf($condition);
             }
         } else {
             $exit('skipIf');

src/Expectation.php

@@ -238,9 +238,6 @@ public function _matcher($matcherName, $actual)
     /**
      * Processes the expectation.
      *
-     * @param  string $matcher The matcher class name.
-     * @param  array  $args    The parameters to pass to the matcher.
-     *
      * @return mixed
      */
     protected function _run()

src/Matcher/AnyException.php

@@ -14,7 +14,7 @@ class AnyException extends \Exception
      * The exception message.
      *
      * @param string $message  The exception message.
-     * @param string $code     The exception code.
+     * @param int    $code     The exception code.
      * @param string $previous The previous exception.
      */
     public function __construct($message = null, $code = 0, $previous = null)

src/Matcher/ToBeCalled.php

@@ -62,8 +62,7 @@ class ToBeCalled
      * Checks that `$actual` will be called.
      *
      * @param  mixed   $actual   The actual value.
-     * @param  mixed   $expected Unused.
-     * @return boolean
+     * @return ToBeCalled
      */
     public static function match($actual)
     {
@@ -73,8 +72,7 @@ public static function match($actual)
     /**
      * Constructor
      *
-     * @param string|object $actual   A fully-namespaced class name or an object instance.
-     * @param string        $expected The expected method method name to be called.
+     * @param string|object $actual A fully-namespaced class name or an object instance.
      */
     public function __construct($actual)
     {

src/Matcher/ToBeFalsy.php

@@ -6,8 +6,10 @@ class ToBeFalsy extends ToEqual
     /**
      * Expect that `$actual` is falsy.
      *
-     * @param  mixed   $actual The actual value.
-     * @return boolean
+     * @param  mixed $actual   The actual value.
+     * @param  mixed $expected The expected value.
+     *
+     * @return bool
      */
     public static function match($actual, $expected = false)
     {

src/Matcher/ToBeNull.php

@@ -6,8 +6,10 @@ class ToBeNull extends ToBe
     /**
      * Expect that `$actual` is `null`.
      *
-     * @param  mixed   $actual The actual value.
-     * @return boolean
+     * @param  mixed $actual The actual value.
+     * @param null $expected The expected vale
+     *
+     * @return bool
      */
     public static function match($actual, $expected = null)
     {

src/Matcher/ToBeTruthy.php

@@ -6,7 +6,8 @@ class ToBeTruthy extends ToEqual
     /**
      * Expect that `$actual` is truthy.
      *
-     * @param  mixed   $actual The actual value.
+     * @param  mixed $actual   The actual value.
+     * @param  mixed $expected The expected value.
      * @return boolean
      */
     public static function match($actual, $expected = true)

src/Matcher/ToEcho.php

@@ -28,7 +28,7 @@ public static function match($actual, $expected = null)
     /**
      * Returns the output generated by the closure.
      *
-     * @param  Closure $actual The actual closure.
+     * @param  \Closure $actual The actual closure.
      * @return string          The string result.
      */
     public static function actual($actual)

src/Matcher/ToReceive.php

@@ -177,9 +177,9 @@ protected function _reference($reference)
     /**
      * Watch a message.
      *
-     * @param string|object $actual A fully-namespaced class name or an object instance.
-     * @param string        $method The expected method method name to be called.
-     * @param object                A message instance.
+     * @param Message $message The message instance
+     *
+     * @return Message
      */
     protected function _watch($message)
     {

src/Matcher/ToThrow.php

@@ -68,8 +68,8 @@ public static function expected($expected, $code = 0)
     /**
      * Compares if two exception are similar.
      *
-     * @param  object $actual   The actual instance.
-     * @param  object $expected The expected instance.
+     * @param  object $actual        The actual instance.
+     * @param  \Exception $exception The exception instance.
      * @return boolean
      */
     public static function _matchException($actual, $exception)

src/Plugin/Call/Calls.php

@@ -42,7 +42,9 @@ public static function log($reference, $call)
      * Helper for the `log()` method.
      *
      * @param object|string $reference An instance or a fully-namespaced class name.
-     * @param string $call             The method name.
+     * @param array $call The method name.
+     *
+     * @return array
      */
     public static function _call($reference, $call)
     {
@@ -103,6 +105,7 @@ public static function lastFindIndex($index = null)
      *
      * @param  object      $message   The message method name.
      * @param  integer     $index     Start index.
+     * @param  integer     $times
      * @param  array       $args      Populated by the list of passed arguments.
      * @return array|false            Return founded log call.
      */

src/Plugin/Double.php

@@ -244,7 +244,7 @@ protected static function _generateImplements($implements)
      *
      * @param  array   $methods  An array of method definitions.
      * @param  boolean $defaults If `true`, Magic Methods will be appended.
-     * @return string            The generated method definitions.
+     * @return array             The generated method definitions.
      */
     protected static function _generateMethodStubs($methods, $defaults = true)
     {
@@ -282,11 +282,10 @@ protected static function _generateMethodStubs($methods, $defaults = true)
      *
      * @param  string  $class A class name.
      * @param  boolean $layer If `true`, all public methods are "overriden".
-     * @return string         The generated methods.
+     * @return array          The generated methods.
      */
     protected static function _generateClassMethods($class, $layer = null)
     {
-        $result = [];
         if (!class_exists($class)) {
             throw new MissingImplementationException("Unexisting class `{$class}`");
         }
@@ -315,7 +314,7 @@ protected static function _generateClassMethods($class, $layer = null)
      *
      * @param  string  $class A class name.
      * @param  integer $mask  The method mask to filter.
-     * @return string         The generated methods.
+     * @return array          The generated methods.
      */
     protected static function _generateAbstractMethods($class)
     {
@@ -336,7 +335,7 @@ protected static function _generateAbstractMethods($class)
      *
      * @param  array   $interfaces A array on interfaces.
      * @param  integer $mask       The method mask to filter.
-     * @return string              The generated methods.
+     * @return array               The generated methods.
      */
     protected static function _generateInterfaceMethods($interfaces, $mask = 255)
     {

src/Plugin/Pointcut.php

@@ -18,7 +18,11 @@ class Pointcut
     /**
      * Point cut called before method execution.
      *
-     * @return boolean If `true` is returned, the normal execution of the method is aborted.
+     * @param string   $method The method name
+     * @param Pointcut $self   The Pointcut instance
+     * @param array    $args   The arguments
+     *
+     * @return bool If `true` is returned, the normal execution of the method is aborted.
      */
     public static function before($method, $self, &$args)
     {

src/Plugin/Stub/Method.php

@@ -114,8 +114,6 @@ public function toBe()
 
     /**
      * Set the stub logic.
-     *
-     * @param Closure $closure The logic.
      */
     public function andRun()
     {

src/Reporter/Coverage.php

@@ -155,14 +155,13 @@ public function metrics()
     /**
      * Outputs some metrics info where the metric is not the total coverage.
      *
-     * @param Metrics $metrics A metrics instance.
-     * @param array   $options The options for the reporter, the options are:
-     *                         - `'verbosity`' _integer|string_: The verbosity level:
-     *                           - 1      : overall coverage value for the whole code.
-     *                           - 2      : overall coverage by namespaces.
-     *                           - 3      : overall coverage by classes.
-     *                           - 4      : overall coverage by methods and functions.
-     *                           - string : coverage for a fully namespaced (class/method/namespace) string.
+     * @param \Kahlan\Reporter\Coverage\Metrics $metrics A metrics instance.
+     * @param int $verbosity The verbosity level:
+     *     - 1      : overall coverage value for the whole code.
+     *     - 2      : overall coverage by namespaces.
+     *     - 3      : overall coverage by classes.
+     *     - 4      : overall coverage by methods and functions.
+     *     - string : coverage for a fully namespaced (class/method/namespace) string.
      */
     protected function _renderMetrics($metrics, $verbosity)
     {
@@ -201,7 +200,7 @@ protected function _renderMetrics($metrics, $verbosity)
      * @param array $metricsReport An array of nested metrics reports extracted according some verbosity.
      * @param array $labelWidth    The width column of the label column used for padding.
      * @param array $lineWidth     The width column of the covered lines data used for padding.
-     * @param array $depth         The actual depth in the reporting to build tree prefix.
+     * @param int   $depth         The actual depth in the reporting to build tree prefix.
      */
     protected function _renderMetricsReport($metricsReport, $labelWidth, $lineWidth, $depth)
     {
@@ -249,17 +248,18 @@ protected function _renderMetricsReport($metricsReport, $labelWidth, $lineWidth,
     /**
      * Extract some metrics reports to display according to a verbosity parameter.
      *
-     * @param Metrics[] $children A array of metrics.
-     * @param array     $options  The options for the reporter, the options are:
-     *                            - `'verbosity`' _integer|string_: The verbosity level:
-     *                              - 1      : overall coverage value for the whole code.
-     *                              - 2      : overall coverage by namespaces.
-     *                              - 3      : overall coverage by classes.
-     *                              - 4      : overall coverage by methods and functions.
-     *                              - string : coverage for a fully namespaced (class/method/namespace) string.
-     * @param array     $depth     The actual depth in the reporting.
-     * @param array     $tab       The size of the tab used for lablels.
-     * @param array     $maxWidth  Will contain the maximum width obtained for labels.
+     * @param \Kahlan\Reporter\Coverage\Metrics[] $children A array of metrics.
+     * @param array $verbosity The verbosity level:
+     *     - 1      : overall coverage value for the whole code.
+     *     - 2      : overall coverage by namespaces.
+     *     - 3      : overall coverage by classes.
+     *     - 4      : overall coverage by methods and functions.
+     *     - string : coverage for a fully namespaced (class/method/namespace) string.
+     * @param int $depth The actual depth in the reporting.
+     * @param int $tab The size of the tab used for lablels.
+     * @param int $maxWidth Will contain the maximum width obtained for labels.
+     *
+     * @return array
      */
     protected function _getMetricsReport($children, $verbosity, $depth = 0, $tab = 3, &$maxWidth = null)
     {

src/Reporter/Coverage/Collector.php

@@ -358,7 +358,6 @@ public function metrics()
      * Helper for `Collector::metrics()`.
      *
      * @param  string  $file     The processed file.
-     * @param  object  $root     The root node of the processed file.
      * @param  object  $nodes    The nodes to collect metrics on.
      * @param  array   $coverage The coverage data.
      * @param  string  $path     The naming of the processed node.
@@ -374,7 +373,6 @@ protected function _processTree($file, $nodes, $coverage, $path = '')
      * Helper for `Collector::metrics()`.
      *
      * @param  string  $file     The processed file.
-     * @param  object  $root     The root node of the processed file.
      * @param  object  $node     The node to collect metrics on.
      * @param  array   $coverage The coverage data.
      * @param  string  $path     The naming of the processed node.

src/Reporter/Coverage/Exporter/Clover.php

@@ -69,9 +69,7 @@ public static function export($options)
     /**
      * Export the coverage of a file.
      *
-     * @param  array   $options The option array where the possible values are:
-     *                          -`'coverage'` The coverage instance.
-     * @return object           The XML file node.
+     * @return object The XML file node.
      */
     protected static function _exportFile($xmlDocument, $file, $data)
     {

src/Reporter/Coverage/Exporter/Istanbul.php

@@ -58,7 +58,6 @@ public static function export($options)
     /**
      * Exports source file coverage
      *
-     * @param  object $collector The collector instance.
      * @return array
      */
     protected static function _export($path, $tree, $coverage)

src/Reporter/Coverage/Exporter/Lcov.php

@@ -58,7 +58,6 @@ public static function export($options)
     /**
      * Exports source file coverage
      *
-     * @param  object $collector The collector instance.
      * @return array
      */
     protected static function _export($path, $tree, $coverage)

src/Reporter/Coverage/Metrics.php

@@ -218,7 +218,6 @@ public function children($name = null)
      * Gets meta info of a metrics from a name reference..
      *
      * @param  string $name The name reference of the metrics.
-     * @param  string $type The type to use by default if not auto detected.
      * @return array        The parsed name.
      */
     protected function _parseName($name)

src/Reporter/Json.php

@@ -49,18 +49,18 @@ public function end($summary)
             }
             switch ($log->type()) {
                 case 'failed':
-                    foreach ($log->children() as $log) {
-                        if ($log->passed()) {
+                    foreach ($log->children() as $child) {
+                        if ($child->passed()) {
                             continue;
                         }
                         $data = [];
-                        foreach ($log->data() as $key => $value) {
+                        foreach ($child->data() as $key => $value) {
                             $data[$key] = Text::toString($value, ['object' => ['method' => $toString]]);
                         }
 
                         $this->_json['errors'][] = [
-                            'spec'  => trim(implode(' ', $log->messages())),
-                            'suite' => $log->file(),
+                            'spec'  => trim(implode(' ', $child->messages())),
+                            'suite' => $child->file(),
                             'data'  => $data
                         ];
                     }

src/Reporter/Terminal.php

@@ -216,8 +216,7 @@ protected function _reportSpec($log)
     /**
      * Print an array of description messages to STDOUT
      *
-     * @param  array   $messages An array of description message.
-     * @return integer           The final message indentation.
+     * @param \Kahlan\Log $log The Log instance
      */
     protected function _reportSuiteMessages($log)
     {
@@ -458,9 +457,9 @@ public function format($string, $options = null)
     /**
      * Humanizes values using an appropriate unit.
      *
-     * @return integer $value     The value.
-     * @return integer $precision The required precision.
-     * @return integer $base      The unit base.
+     * @param  integer $value     The value.
+     * @param  integer $precision The required precision.
+     * @param  integer $base      The unit base.
      * @return string             The Humanized string value.
      */
     public function readableSize($value, $precision = 0, $base = 1024)