minor #47 Improved some PHPdoc comments (javiereguiluz)

This PR was merged into the 1.0-dev branch.

Discussion
----------

Improved some PHPdoc comments

Commits
-------

6a894ad Improved some PHPdoc comments

Author: fabpot

src/Command/AbstractCommand.php

@@ -41,32 +41,34 @@ public function __construct(Generator $generator)
     }
 
     /**
-     * Returns the parameters used to parse the file templates, to generate the
-     * file names, etc.
+     * Returns the values used to fill in the skeleton files of the generated
+     * code and the success/error messages as pairs of param_name => param_value.
+     * (e.g. ['user' => 'Jane', 'project_dir' => realpath(__DIR__.'/..')])
      */
     abstract protected function getParameters(): array;
 
     /**
-     * Returns the list of files to generate and the templates used to do that.
+     * Returns the list of files to generate as pairs of skeleton_filepath => generated_filepath
+     * Skeleton files must be absolute paths and generated paths are relative to the app.
+     * (e.g. [__DIR__.'/../Resources/skeleton/command/Command.php.txt' => 'src/Command/'.$params['command_class_name'].'.php'])
      */
     abstract protected function getFiles(array $params): array;
 
     /**
-     * Override to add a final "next steps" message.
-     *
-     * @param array $params
-     * @param ConsoleStyle $io
+     * Optional information displayed to the user after all files have been generated.
      */
     abstract protected function writeNextStepsMessage(array $params, ConsoleStyle $io);
 
+    /**
+     * Defines the optional or required dependencies of the maker command, which are
+     * checked before running the command and used to display actionable error messages.
+     */
     abstract protected function configureDependencies(DependencyBuilder $dependencies);
 
     /**
      * Call in configure() to disable the automatic interactive prompt for an arg.
-     *
-     * @param string $argumentName
      */
-    protected function setArgumentAsNonInteractive($argumentName)
+    protected function setArgumentAsNonInteractive(string $argumentName)
     {
         $this->nonInteractiveArguments[] = $argumentName;
     }

src/Str.php

@@ -18,34 +18,37 @@
 final class Str
 {
     /**
-     * Looks for suffixes in a case-insensitive way.
+     * Looks for suffixes in strings in a case-insensitive way.
      */
     public static function hasSuffix(string $value, string $suffix): bool
     {
         return 0 === strcasecmp($suffix, substr($value, -strlen($suffix)));
     }
 
     /**
-     * Ensures that the given string ends with the given suffix. It works in a
-     * case-insensitive way (e.g. value: 'Foocommand' suffix: 'Command' -> result: 'FooCommand'
+     * Ensures that the given string ends with the given suffix. If the string
+     * already contains the suffix, it's not added twice. It's case-insensitive
+     * (e.g. value: 'Foocommand' suffix: 'Command' -> result: 'FooCommand')
      */
     public static function addSuffix(string $value, string $suffix): string
     {
         return self::removeSuffix($value, $suffix).$suffix;
     }
 
     /**
-     * Ensures that the given string doesn't end with the given suffix. It works in a
-     * case-insensitive way (e.g. value: 'Foocommand' suffix: 'Command' -> result: 'Foo'
+     * Ensures that the given string doesn't end with the given suffix. If the
+     * string contains the suffix multiple times, only the last one is removed.
+     * It's case-insensitive (e.g. value: 'Foocommand' suffix: 'Command' -> result: 'Foo'
      */
     public static function removeSuffix(string $value, string $suffix): string
     {
         return self::hasSuffix($value, $suffix) ? substr($value, 0, -strlen($suffix)) : $value;
     }
 
     /**
-     * Transforms the given string into the format commonly used by PHP classes
-     * (e.g. `app:do_this-and_that` -> `AppDoThisAndThat`)
+     * Transforms the given string into the format commonly used by PHP classes,
+     * (e.g. `app:do_this-and_that` -> `AppDoThisAndThat`) but it doesn't check
+     * the validity of the class name.
      */
     public static function asClassName(string $value, string $suffix = ''): string
     {