[console | in-code documentation] Parameters not documented.

[PSF1]

Hi,

The parameters $name and $description, in Command::addOption, are not documented in code.

Please see: Source code

Thx :)

[xabbuh]

Well, $name and $description are quite self-explanatory, aren't they? What would you add that would provide additional value?

[PSF1]

The IDE intellisense only show how parameter $shortcut, $mode and $default, not $name, and not $description.

While I searching for documentation about how add option's name, I found https://symfony.com/doc/current/console/input.html#using-command-options where I could saw all the parameters. This fuzzed me... Then I go to the code and I see the problem, that parameters are not documented in annotation, and I created this issue.

I'm sorry if I hurt feelings to any person with this, it was not my intention.

[javiereguiluz]

@PSF1 no worries! Your proposal, as any other proposal, is very well received and we thank you for that.

I think the problem here is that:

(1) @xabbuh is right that from the point of view of code, these two arguments are obvious and that's why they don't need any explanation
(2) however, from the point of view of docs, they are not obvious. We jut display a bunch of arguments and we don't explain which is one. That why I agree on your comment.

I think we should mention the arguments of input options and arguments the first time we mention them.

E.g. instead of this:

// ...
use Symfony\Component\Console\Input\InputOption;

$this
    // ...
    ->addOption(
        'iterations',
        null,
        InputOption::VALUE_REQUIRED,
        'How many times should the message be printed?',
        1
    )
;

Use something like:

// ...
use Symfony\Component\Console\Input\InputOption;

$this
    // ...
    ->addOption(
        // this is the name that users must type to pass this option
        'iterations',
        // this is the shortcut, which is another way to pass this option and
        // it's useful for common options or options with long names
        null,
        // this is the type of option (e.g. requires a value, can be passed more than once, etc.)
        InputOption::VALUE_REQUIRED,
        // the option description displayed in the command help
        'How many times should the message be printed?',
        // the default value of the option (for those which allow to pass values)
        1
    )
;

What do you think?

[PSF1]

Thanks @javiereguiluz , I'm sorry for not replying before.

I meant about the code:
https://github.com/symfony/console/blob/0a4f498e8a2599f269edfd8605b5f03154b7074b/Command/Command.php#L449

/**
     * Adds an option.
     *
     * @param string|array|null $shortcut The shortcuts, can be null, a string of shortcuts delimited by | or an array of shortcuts
     * @param int|null          $mode     The option mode: One of the InputOption::VALUE_* constants
     * @param mixed             $default  The default value (must be null for InputOption::VALUE_NONE)
     *
     * @throws InvalidArgumentException If option mode is invalid or incompatible
     *
     * @return $this
     */
    public function addOption(string $name, $shortcut = null, int $mode = null, string $description = '', $default = null)
    {
        $this->definition->addOption(new InputOption($name, $shortcut, $mode, $description, $default));
        if (null !== $this->fullDefinition) {
            $this->fullDefinition->addOption(new InputOption($name, $shortcut, $mode, $description, $default));
        }

        return $this;
    }

The code comment describes 3 parameters but the function has 5 parameters. That confuses some IDEs.

[wouterj]

Please report this to Intellisense instead. Not having a PHPdoc for all parameters is valid for most tools and with the introduction of strict typing in PHP, PHPdocs are less and less useful.