From 3ab4262d8a686281178a051aebc20637c4f2844e Mon Sep 17 00:00:00 2001 From: Maxime STEINHAUSSER Date: Wed, 7 Dec 2016 12:55:24 +0100 Subject: [PATCH 1/2] [Console] Review Application docblocks --- src/Symfony/Component/Console/Application.php | 79 ++++++------------- 1 file changed, 23 insertions(+), 56 deletions(-) diff --git a/src/Symfony/Component/Console/Application.php b/src/Symfony/Component/Console/Application.php index b11268ade33bf..a3d8ac820ecc5 100644 --- a/src/Symfony/Component/Console/Application.php +++ b/src/Symfony/Component/Console/Application.php @@ -72,8 +72,6 @@ class Application private $defaultCommand; /** - * Constructor. - * * @param string $name The name of the application * @param string $version The version of the application */ @@ -103,7 +101,8 @@ public function setDispatcher(EventDispatcherInterface $dispatcher) * * @return int 0 if everything went fine, or an error code * - * @throws \Exception When doRun returns Exception + * @throws \Exception When doRun threw an exception and catchExceptions is false + * @throws \Throwable When doRun threw a throwable */ public function run(InputInterface $input = null, OutputInterface $output = null) { @@ -196,7 +195,7 @@ public function doRun(InputInterface $input, OutputInterface $output) /** * Set a helper set to be used with the command. * - * @param HelperSet $helperSet The helper set + * @param HelperSet $helperSet */ public function setHelperSet(HelperSet $helperSet) { @@ -204,8 +203,6 @@ public function setHelperSet(HelperSet $helperSet) } /** - * Get the helper set associated with the command. - * * @return HelperSet The HelperSet instance associated with this command */ public function getHelperSet() @@ -216,7 +213,7 @@ public function getHelperSet() /** * Set an input definition to be used with this application. * - * @param InputDefinition $definition The input definition + * @param InputDefinition $definition */ public function setDefinition(InputDefinition $definition) { @@ -224,9 +221,7 @@ public function setDefinition(InputDefinition $definition) } /** - * Gets the InputDefinition related to this Application. - * - * @return InputDefinition The InputDefinition instance + * @return InputDefinition The InputDefinition related to this Application */ public function getDefinition() { @@ -234,9 +229,7 @@ public function getDefinition() } /** - * Gets the help message. - * - * @return string A help message + * @return string The help message */ public function getHelp() { @@ -244,8 +237,6 @@ public function getHelp() } /** - * Sets whether to catch exceptions or not during commands execution. - * * @param bool $boolean Whether to catch exceptions or not during commands execution */ public function setCatchExceptions($boolean) @@ -254,8 +245,6 @@ public function setCatchExceptions($boolean) } /** - * Sets whether to automatically exit after a command execution or not. - * * @param bool $boolean Whether to automatically exit after a command execution or not */ public function setAutoExit($boolean) @@ -264,8 +253,6 @@ public function setAutoExit($boolean) } /** - * Gets the name of the application. - * * @return string The application name */ public function getName() @@ -276,7 +263,7 @@ public function getName() /** * Sets the application name. * - * @param string $name The application name + * @param string $name */ public function setName($name) { @@ -284,8 +271,6 @@ public function setName($name) } /** - * Gets the application version. - * * @return string The application version */ public function getVersion() @@ -294,8 +279,6 @@ public function getVersion() } /** - * Sets the application version. - * * @param string $version The application version */ public function setVersion($version) @@ -304,8 +287,6 @@ public function setVersion($version) } /** - * Returns the long version of the application. - * * @return string The long application version */ public function getLongVersion() @@ -338,7 +319,7 @@ public function register($name) * * If a Command is not enabled it will not be added. * - * @param Command[] $commands An array of commands + * @param Command[] $commands */ public function addCommands(array $commands) { @@ -353,7 +334,7 @@ public function addCommands(array $commands) * If a command with the same name already exists, it will be overridden. * If the command is not enabled it will not be added. * - * @param Command $command A Command object + * @param Command $command * * @return Command|null The registered command if enabled or null */ @@ -385,9 +366,9 @@ public function add(Command $command) * * @param string $name The command name or alias * - * @return Command A Command object + * @return Command * - * @throws \InvalidArgumentException When command name given does not exist + * @throws \InvalidArgumentException When given command name does not exist */ public function get($name) { @@ -410,8 +391,6 @@ public function get($name) } /** - * Returns true if the command exists, false otherwise. - * * @param string $name The command name or alias * * @return bool true if the command exists, false otherwise @@ -489,7 +468,7 @@ public function findNamespace($namespace) * * @param string $name A command name or a command alias * - * @return Command A Command instance + * @return Command * * @throws \InvalidArgumentException When command name is incorrect or ambiguous */ @@ -546,7 +525,7 @@ public function find($name) * * @param string $namespace A namespace name * - * @return Command[] An array of Command instances + * @return Command[] */ public function all($namespace = null) { @@ -565,11 +544,9 @@ public function all($namespace = null) } /** - * Returns an array of possible abbreviations given a set of names. + * @param string[] $names An array of names * - * @param array $names An array of names - * - * @return array An array of abbreviations + * @return array An array of possible abbreviations given a set of names. */ public static function getAbbreviations($names) { @@ -832,7 +809,7 @@ protected function configureIO(InputInterface $input, OutputInterface $output) * * @return int 0 if everything went fine, or an error code * - * @throws \Exception when the command being run threw an exception + * @throws \Throwable|\Exception when the command being run threw an throwable */ protected function doRunCommand(Command $command, InputInterface $input, OutputInterface $output) { @@ -882,11 +859,9 @@ protected function doRunCommand(Command $command, InputInterface $input, OutputI } /** - * Gets the name of the command based on input. - * - * @param InputInterface $input The input interface + * @param InputInterface $input * - * @return string The command name + * @return string The command name based on input */ protected function getCommandName(InputInterface $input) { @@ -894,9 +869,7 @@ protected function getCommandName(InputInterface $input) } /** - * Gets the default input definition. - * - * @return InputDefinition An InputDefinition instance + * @return InputDefinition The default input definition */ protected function getDefaultInputDefinition() { @@ -914,9 +887,7 @@ protected function getDefaultInputDefinition() } /** - * Gets the default commands that should always be available. - * - * @return Command[] An array of default Command instances + * @return Command[] The default commands that should always be available */ protected function getDefaultCommands() { @@ -924,9 +895,7 @@ protected function getDefaultCommands() } /** - * Gets the default helper set with the helpers that should always be available. - * - * @return HelperSet A HelperSet instance + * @return HelperSet The default helper set with the helpers that should always be available */ protected function getDefaultHelperSet() { @@ -1073,7 +1042,7 @@ private function findAlternatives($name, $collection) /** * Sets the default Command name. * - * @param string $commandName The Command name + * @param string $commandName */ public function setDefaultCommand($commandName) { @@ -1130,11 +1099,9 @@ private function splitStringByWidth($string, $width) } /** - * Returns all namespaces of the command name. - * * @param string $name The full name of the command * - * @return string[] The namespaces of the command + * @return string[] The namespaces of the command name */ private function extractAllNamespaces($name) { From a80c5f73cdf1c455cb5910a674653b601728164f Mon Sep 17 00:00:00 2001 From: Maxime STEINHAUSSER Date: Wed, 7 Dec 2016 16:11:29 +0100 Subject: [PATCH 2/2] [Console] Review Application docblocks --- src/Symfony/Component/Console/Application.php | 77 +++++++++++++------ 1 file changed, 53 insertions(+), 24 deletions(-) diff --git a/src/Symfony/Component/Console/Application.php b/src/Symfony/Component/Console/Application.php index a3d8ac820ecc5..a9400127e6da4 100644 --- a/src/Symfony/Component/Console/Application.php +++ b/src/Symfony/Component/Console/Application.php @@ -72,6 +72,8 @@ class Application private $defaultCommand; /** + * Constructor. + * * @param string $name The name of the application * @param string $version The version of the application */ @@ -100,9 +102,6 @@ public function setDispatcher(EventDispatcherInterface $dispatcher) * @param OutputInterface $output An Output instance * * @return int 0 if everything went fine, or an error code - * - * @throws \Exception When doRun threw an exception and catchExceptions is false - * @throws \Throwable When doRun threw a throwable */ public function run(InputInterface $input = null, OutputInterface $output = null) { @@ -195,7 +194,7 @@ public function doRun(InputInterface $input, OutputInterface $output) /** * Set a helper set to be used with the command. * - * @param HelperSet $helperSet + * @param HelperSet $helperSet The helper set */ public function setHelperSet(HelperSet $helperSet) { @@ -203,6 +202,8 @@ public function setHelperSet(HelperSet $helperSet) } /** + * Get the helper set associated with the command. + * * @return HelperSet The HelperSet instance associated with this command */ public function getHelperSet() @@ -213,7 +214,7 @@ public function getHelperSet() /** * Set an input definition to be used with this application. * - * @param InputDefinition $definition + * @param InputDefinition $definition The input definition */ public function setDefinition(InputDefinition $definition) { @@ -221,7 +222,9 @@ public function setDefinition(InputDefinition $definition) } /** - * @return InputDefinition The InputDefinition related to this Application + * Gets the InputDefinition related to this Application. + * + * @return InputDefinition The InputDefinition instance */ public function getDefinition() { @@ -229,7 +232,9 @@ public function getDefinition() } /** - * @return string The help message + * Gets the help message. + * + * @return string A help message */ public function getHelp() { @@ -237,6 +242,8 @@ public function getHelp() } /** + * Sets whether to catch exceptions or not during commands execution. + * * @param bool $boolean Whether to catch exceptions or not during commands execution */ public function setCatchExceptions($boolean) @@ -245,6 +252,8 @@ public function setCatchExceptions($boolean) } /** + * Sets whether to automatically exit after a command execution or not. + * * @param bool $boolean Whether to automatically exit after a command execution or not */ public function setAutoExit($boolean) @@ -253,6 +262,8 @@ public function setAutoExit($boolean) } /** + * Gets the name of the application. + * * @return string The application name */ public function getName() @@ -263,7 +274,7 @@ public function getName() /** * Sets the application name. * - * @param string $name + * @param string $name The application name */ public function setName($name) { @@ -271,6 +282,8 @@ public function setName($name) } /** + * Gets the application version. + * * @return string The application version */ public function getVersion() @@ -279,6 +292,8 @@ public function getVersion() } /** + * Sets the application version. + * * @param string $version The application version */ public function setVersion($version) @@ -287,6 +302,8 @@ public function setVersion($version) } /** + * Returns the long version of the application. + * * @return string The long application version */ public function getLongVersion() @@ -319,7 +336,7 @@ public function register($name) * * If a Command is not enabled it will not be added. * - * @param Command[] $commands + * @param Command[] $commands An array of commands */ public function addCommands(array $commands) { @@ -334,7 +351,7 @@ public function addCommands(array $commands) * If a command with the same name already exists, it will be overridden. * If the command is not enabled it will not be added. * - * @param Command $command + * @param Command $command A Command object * * @return Command|null The registered command if enabled or null */ @@ -366,7 +383,7 @@ public function add(Command $command) * * @param string $name The command name or alias * - * @return Command + * @return Command A Command object * * @throws \InvalidArgumentException When given command name does not exist */ @@ -391,6 +408,8 @@ public function get($name) } /** + * Returns true if the command exists, false otherwise. + * * @param string $name The command name or alias * * @return bool true if the command exists, false otherwise @@ -468,7 +487,7 @@ public function findNamespace($namespace) * * @param string $name A command name or a command alias * - * @return Command + * @return Command A Command instance * * @throws \InvalidArgumentException When command name is incorrect or ambiguous */ @@ -525,7 +544,7 @@ public function find($name) * * @param string $namespace A namespace name * - * @return Command[] + * @return Command[] An array of Command instances */ public function all($namespace = null) { @@ -544,9 +563,11 @@ public function all($namespace = null) } /** - * @param string[] $names An array of names + * Returns an array of possible abbreviations given a set of names. + * + * @param array $names An array of names * - * @return array An array of possible abbreviations given a set of names. + * @return array An array of abbreviations */ public static function getAbbreviations($names) { @@ -808,8 +829,6 @@ protected function configureIO(InputInterface $input, OutputInterface $output) * @param OutputInterface $output An Output instance * * @return int 0 if everything went fine, or an error code - * - * @throws \Throwable|\Exception when the command being run threw an throwable */ protected function doRunCommand(Command $command, InputInterface $input, OutputInterface $output) { @@ -859,9 +878,11 @@ protected function doRunCommand(Command $command, InputInterface $input, OutputI } /** - * @param InputInterface $input + * Gets the name of the command based on input. + * + * @param InputInterface $input The input interface * - * @return string The command name based on input + * @return string The command name */ protected function getCommandName(InputInterface $input) { @@ -869,7 +890,9 @@ protected function getCommandName(InputInterface $input) } /** - * @return InputDefinition The default input definition + * Gets the default input definition. + * + * @return InputDefinition An InputDefinition instance */ protected function getDefaultInputDefinition() { @@ -887,7 +910,9 @@ protected function getDefaultInputDefinition() } /** - * @return Command[] The default commands that should always be available + * Gets the default commands that should always be available. + * + * @return Command[] An array of default Command instances */ protected function getDefaultCommands() { @@ -895,7 +920,9 @@ protected function getDefaultCommands() } /** - * @return HelperSet The default helper set with the helpers that should always be available + * Gets the default helper set with the helpers that should always be available. + * + * @return HelperSet A HelperSet instance */ protected function getDefaultHelperSet() { @@ -1042,7 +1069,7 @@ private function findAlternatives($name, $collection) /** * Sets the default Command name. * - * @param string $commandName + * @param string $commandName The Command name */ public function setDefaultCommand($commandName) { @@ -1099,9 +1126,11 @@ private function splitStringByWidth($string, $width) } /** + * Returns all namespaces of the command name. + * * @param string $name The full name of the command * - * @return string[] The namespaces of the command name + * @return string[] The namespaces of the command */ private function extractAllNamespaces($name) {