Improve command docs texts (#4479)

* Improve command docs texts

* Tweaks

* Add example of Drupal6 style db-url

src/Commands/DrushCommands.php

@@ -34,6 +34,11 @@ abstract class DrushCommands implements IOAwareInterface, LoggerAwareInterface,
         io as roboIo;
     }
 
+    /**
+     * @var CommandData
+     */
+    protected $commandData;
+
     public function __construct()
     {
     }
@@ -91,7 +96,19 @@ protected function printFile($file)
     }
 
     /**
-     * Print the contents of a file. The path comes the @topic annotation.
+     * Persist commandData for use in primary command callback. Used by 'topic' commands.
+     *
+     * @hook pre-command *
+     *
+     * @param \Consolidation\AnnotatedCommand\CommandData $commandData
+     */
+    public function preHook(CommandData $commandData)
+    {
+        $this->commandData = $commandData;
+    }
+
+    /**
+     * Print the contents of a file. The path comes from the @topic annotation.
      *
      * @param CommandData $commandData
      *   Full path to a file.

src/Commands/OptionsCommands.php

@@ -23,6 +23,7 @@ public function optionsetProcBuild($options = ['ssh-options' => self::REQ, 'tty'
     /**
      * @hook option @optionset_get_editor
      * @option editor A string of bash which launches user's preferred text editor. Defaults to <info>${VISUAL-${EDITOR-vi}}</info>.
+     * @option bg Launch editor in background process.
      */
     public function optionsetGetEditor($options = ['editor' => '', 'bg' => false])
     {
@@ -39,7 +40,7 @@ public function optionsetSsh($options = ['ssh-options' => self::REQ])
     /**
      * @hook option @optionset_sql
      * @option database The DB connection key if using multiple connections in settings.php.
-     * @option db-url A Drupal 6 style database URL.
+     * @option db-url A Drupal 6 style database URL. For example <info>mysql://root:pass@localhost:port/dbname</info>
      * @option target The name of a target within the specified database connection.
      * @option show-passwords Show password on the CLI. Useful for debugging.
      */

src/Commands/core/DocsCommands.php

@@ -3,7 +3,6 @@
 
 use Consolidation\AnnotatedCommand\CommandData;
 use Drush\Commands\DrushCommands;
-use Webmozart\PathUtil\Path;
 
 /**
  * Topic commands.
@@ -14,11 +13,6 @@
  */
 class DocsCommands extends DrushCommands
 {
-    /**
-     * @var CommandData
-     */
-    protected $commandData;
-
     /**
      * README.md
      *
@@ -85,7 +79,7 @@ public function configExport()
     }
 
     /**
-     * Output formatters and filters: how to control the output produced by Drush commands
+     * Output formatters and filters: control the command output
      *
      * @command docs:output-formats-filters
      * @aliases docs:output
@@ -214,14 +208,4 @@ public function deploy()
     {
         self::printFileTopic($this->commandData);
     }
-
-    /**
-     * @hook pre-command *
-     *
-     * @param \Consolidation\AnnotatedCommand\CommandData $commandData
-     */
-    public function pre(CommandData $commandData)
-    {
-        $this->commandData = $commandData;
-    }
 }

src/Commands/core/MkCommands.php

@@ -52,7 +52,7 @@ public function docs($options = ['destination' => self::REQ])
                 if ($command->getDescription()) {
                     $body .= self::cliTextToMarkdown($command->getDescription()) ."\n\n";
                     if ($command->getHelp()) {
-                        $body .= $command->getHelp(). "\n\n";
+                        $body .= self::cliTextToMarkdown($command->getHelp()). "\n\n";
                     }
                 }
                 if ($examples = $command->getExampleUsages()) {
@@ -71,14 +71,16 @@ public function docs($options = ['destination' => self::REQ])
                     $body .= "\n";
                 }
                 if ($opts = $command->getDefinition()->getOptions()) {
-                    $body .= "#### Options\n\n";
+                    $body_opt = '';
                     foreach ($opts as $opt) {
                         if (!HelpCLIFormatter::isGlobalOption($opt->getName())) {
                             $opt_array = self::optionToArray($opt);
-                            $body .= '- **' . HelpCLIFormatter::formatOptionKeys($opt_array) . '**. ' . self::cliTextToMarkdown(HelpCLIFormatter::formatOptionDescription($opt_array)) . "\n";
+                            $body_opt .= '- **' . HelpCLIFormatter::formatOptionKeys($opt_array) . '**. ' . self::cliTextToMarkdown(HelpCLIFormatter::formatOptionDescription($opt_array)) . "\n";
                         }
                     }
-                    $body .= "\n";
+                    if ($body_opt) {
+                        $body .= "#### Options\n\n$body_opt\n";
+                    }
                 }
                 if ($topics = $command->getTopics()) {
                     $body .= "#### Topics\n\n";
@@ -147,7 +149,7 @@ protected function writeyml($nav, $dest)
             'markdown_extensions' => [
                 ['toc' => [
                     'toc_depth' => 0,
-                    'permalink' => true,
+                    'permalink' => '',
                 ]],
                 ['admonition' => []],
             ],

src/Commands/core/PhpCommands.php

@@ -15,12 +15,10 @@ class PhpCommands extends DrushCommands implements StdinAwareInterface
      *
      * @command php:eval
      * @param $code PHP code
-     * @usage drush php:eval 'variable_set("hello", "world");'
-     *   Sets the hello variable using Drupal API.'
      * @usage drush php:eval '$node = node_load(1); print $node->title;'
      *   Loads node with nid 1 and then prints its title.
      * @usage drush php:eval "file_unmanaged_copy(\'$HOME/Pictures/image.jpg\', \'public://image.jpg\');"
-     *   Copies a file whose path is determined by an environment\'s variable. Note the use of double quotes so the variable $HOME gets replaced by its value.
+     *   Copies a file whose path is determined by an environment's variable. Use of double quotes so the variable $HOME gets replaced by its value.
      * @usage drush php:eval "node_access_rebuild();"
      *   Rebuild node access permissions.
      * @aliases eval,ev,php-eval
@@ -38,7 +36,7 @@ public function evaluate($code, $options = ['format' => 'var_export'])
      * can't be bothered to figure out bash quoting. If you plan to share a
      * script with others, consider making a full Drush command instead, since
      * that's more self-documenting.  Drush provides commandline options to the
-     * script via a variable called $extra.
+     * script via a variable called <info>$extra</info>.
      *
      * @command php:script
      * @option script-path Additional paths to search for scripts, separated by
@@ -50,8 +48,8 @@ public function evaluate($code, $options = ['format' => 'var_export'])
      * @usage drush php:script
      *   List all available scripts.
      * @usage drush php:script foo -- apple --cider
-     *   Run foo.php script with argument 'apple' and option 'cider'. Note the
-     *   -- separator.
+     *   Run foo.php script with argument <info>apple</info> and option <info>cider</info>. Note the
+     *   <info>--</info> separator.
      * @aliases scr,php-script
      * @bootstrap max
      * @throws \Exception

src/Commands/core/RsyncCommands.php

@@ -41,7 +41,7 @@ public function __construct()
      *
      * @command core:rsync
      * @param $source A site alias and optional path. See rsync documentation and example.site.yml.
-     * @param $target A site alias and optional path. See rsync documentation and example.site.yml.',
+     * @param $target A site alias and optional path. See rsync documentation and example.site.yml.
      * @param $extra Additional parameters after the ssh statement.
      * @optionset_ssh
      * @option exclude-paths List of paths to exclude, seperated by : (Unix-based systems) or ; (Windows).
@@ -50,7 +50,7 @@ public function __construct()
      * @usage drush rsync @dev @stage
      *   Rsync Drupal root from Drush alias dev to the alias stage.
      * @usage drush rsync ./ @stage:%files/img
-     *   Rsync all files in the current directory to the 'img' directory in the file storage folder on the Drush alias stage.
+     *   Rsync all files in the current directory to the <info>img</info>directory in the file storage folder on the Drush alias stage.
      * @usage drush rsync @dev @stage -- --exclude=*.sql --delete
      *   Rsync Drupal root from the Drush alias dev to the alias stage, excluding all .sql files and delete all files on the destination that are no longer on the source.
      * @usage drush rsync @dev @stage --ssh-options="-o StrictHostKeyChecking=no" -- --delete

src/Commands/core/SiteCommands.php

@@ -25,7 +25,7 @@ class SiteCommands extends DrushCommands implements SiteAliasManagerAwareInterfa
      *
      * @command site:set
      *
-     * @param string $site Site specification to use, or "-" for previous site. Omit this argument to unset.
+     * @param string $site Site specification to use, or <info>-</info> for previous site. Omit this argument to unset.
      *
      * @throws \Exception
      * @handle-remote-commands

src/Commands/core/SiteInstallCommands.php

@@ -26,20 +26,20 @@ class SiteInstallCommands extends DrushCommands implements SiteAliasManagerAware
      * Install Drupal along with modules/themes/configuration/profile.
      *
      * @command site:install
-     * @param $profile An install profile name. Defaults to 'standard' unless an install profile is marked as a distribution. Additional info for the install profile may also be provided with additional arguments. The key is in the form [form name].[parameter name]
+     * @param $profile An install profile name. Defaults to <info>standard</info> unless an install profile is marked as a distribution. Additional info for the install profile may also be provided with additional arguments. The key is in the form <info>[form name].[parameter name]</info>
      * @option db-url A Drupal 6 style database URL. Required for initial install, not re-install. If omitted and required, Drush prompts for this item.
      * @option db-prefix An optional table prefix to use for initial install.
      * @option db-su Account to use when creating a new database. Must have Grant permission (mysql only). Optional.
-     * @option db-su-pw Password for the "db-su" account. Optional.
-     * @option account-name uid1 name. Defaults to admin
+     * @option db-su-pw Password for the <info>db-su</info> account. Optional.
+     * @option account-name uid1 name.
      * @option account-pass uid1 pass. Defaults to a randomly generated password. If desired, set a fixed password in config.yml.
-     * @option account-mail uid1 email. Defaults to admin@example.com
+     * @option account-mail uid1 email.
      * @option locale A short language code. Sets the default site language. Language files must already be present.
-     * @option site-name Defaults to Site-Install
-     * @option site-mail From: for system mailings. Defaults to admin@example.com
-     * @option sites-subdir Name of directory under 'sites' which should be created.
+     * @option site-name
+     * @option site-mail <info>From:</info> for system mailings.
+     * @option sites-subdir Name of directory under <info>sites</info> which should be created.
      * @option config-dir Deprecated - only use with Drupal 8.5-. A path pointing to a full set of configuration which should be installed during installation.
-     * @option existing-config Configuration from "sync" directory should be imported during installation. Use with Drupal 8.6+.
+     * @option existing-config Configuration from <info>sync</info> directory should be imported during installation. Use with Drupal 8.6+.
      * @usage drush si expert --locale=uk
      *   (Re)install using the expert install profile. Set default language to Ukrainian.
      * @usage drush si --db-url=mysql://root:pass@localhost:port/dbname

src/Commands/core/SshCommands.php

@@ -15,6 +15,7 @@ class SshCommands extends DrushCommands implements SiteAliasManagerAwareInterfac
      * command.
      *
      * @command site:ssh
+     * @param $code Code which should run at remote host.
      * @option cd Directory to change to. Defaults to Drupal root.
      * @optionset_proc_build
      * @handle-remote-commands
@@ -29,24 +30,24 @@ class SshCommands extends DrushCommands implements SiteAliasManagerAwareInterfac
      * @aliases ssh,site-ssh
      * @topics docs:aliases
      */
-    public function ssh(array $args, $options = ['cd' => self::REQ, 'tty' => false])
+    public function ssh(array $code, $options = ['cd' => self::REQ, 'tty' => false])
     {
         $alias = $this->siteAliasManager()->getSelf();
 
-        if (empty($args)) {
-            $args[] = 'bash';
-            $args[] = '-l';
+        if (empty($code)) {
+            $code[] = 'bash';
+            $code[] = '-l';
 
             // We're calling an interactive 'bash' shell, so we want to
             // force tty to true.
             $options['tty'] = true;
         }
 
-        if ((count($args) == 1)) {
-            $args = [Shell::preEscaped($args[0])];
+        if ((count($code) == 1)) {
+            $code = [Shell::preEscaped($code[0])];
         }
 
-        $process = $this->processManager()->siteProcess($alias, $args);
+        $process = $this->processManager()->siteProcess($alias, $code);
         $process->setTty($options['tty']);
         // The transport handles the chdir during processArgs().
         $fallback = $alias->hasRoot() ? $alias->root() : null;

src/Commands/pm/SecurityUpdateCommands.php

@@ -37,11 +37,9 @@ public static function composerLockPath(): string
     /**
      * Check Drupal Composer packages for pending security updates.
      *
-     * This uses the Drupal security advisories package to determine if updates
+     * This uses the [Drupal security advisories package](https://github.com/drupal-composer/drupal-security-advisories) to determine if updates
      * are available.
      *
-     * @see https://github.com/drupal-composer/drupal-security-advisories
-     *
      * @command pm:security
      * @aliases sec,pm-security
      * @bootstrap none

src/Commands/sql/SqlCommands.php

@@ -215,13 +215,13 @@ public function query($query = '', $options = ['result-file' => null, 'file' =>
      * @option create-db Omit DROP TABLE statements. Used by Postgres and Oracle only.
      * @option data-only Dump data without statements to create any of the schema.
      * @option ordered-dump Order by primary key and add line breaks for efficient diffs. Slows down the dump. Mysql only.
-     * @option gzip Compress the dump using the gzip program which must be in your $PATH.
+     * @option gzip Compress the dump using the gzip program which must be in your <info>$PATH</info>.
      * @option extra Add custom arguments/options when connecting to database (used internally to list tables).
-     * @option extra-dump Add custom arguments/options to the dumping of the database (e.g. mysqldump command).
+     * @option extra-dump Add custom arguments/options to the dumping of the database (e.g. <info>mysqldump</info> command).
      * @usage drush sql:dump --result-file=../18.sql
      *   Save SQL dump to the directory above Drupal root.
      * @usage drush sql:dump --skip-tables-key=common
-     *   Skip standard tables. @see example.drush.yml
+     *   Skip standard tables. See examples/example.drush.yml
      * @usage drush sql:dump --extra-dump=--no-data
      *   Pass extra option to mysqldump command.
      * @hidden-options create-db
@@ -232,7 +232,7 @@ public function query($query = '', $options = ['result-file' => null, 'file' =>
      * @return \Consolidation\OutputFormatters\StructuredData\PropertyList
      *
      * @notes
-     *   createdb is used by sql-sync, since including the DROP TABLE statements interfere with the import when the database is created.
+     *   --createdb is used by sql-sync, since including the DROP TABLE statements interferes with the import when the database is created.
      */
     public function dump($options = ['result-file' => self::REQ, 'create-db' => false, 'data-only' => false, 'ordered-dump' => false, 'gzip' => false, 'extra' => self::REQ, 'extra-dump' => self::REQ, 'format' => 'null'])
     {

src/Commands/sql/SqlSyncCommands.php

@@ -24,9 +24,9 @@ class SqlSyncCommands extends DrushCommands implements SiteAliasManagerAwareInte
      * @optionset_table_selection
      * @option no-dump Do not dump the sql database; always use an existing dump file.
      * @option no-sync Do not rsync the database dump file from source to target.
-     * @option runner Where to run the rsync command; defaults to the local site. Can also be 'source' or 'target'.
+     * @option runner Where to run the rsync command; defaults to the local site. Can also be <info>source</info> or <info>target</info>.
      * @option create-db Create a new database before importing the database dump on the target machine.
-     * @option db-su Account to use when creating a new database (e.g. root).
+     * @option db-su Account to use when creating a new database (e.g. <info>root</info>).
      * @option db-su-pw Password for the db-su account.
      * @option source-dump The path for retrieving the sql-dump on source machine.
      * @option target-dump The path for storing the sql-dump on target machine.

src/Drupal/Commands/core/CliCommands.php

@@ -22,11 +22,11 @@ class CliCommands extends DrushCommands
      * @command docs:repl
      * @aliases docs-repl
      * @hidden
-     * @topic
+     * @topic ../../../../docs/repl.md
      */
     public function docs()
     {
-        self::printFile(DRUSH_BASE_PATH. '/docs/repl.md');
+        self::printFileTopic($this->commandData);
     }
 
     /**
@@ -35,12 +35,11 @@ public function docs()
      * @aliases php,core:cli,core-cli
      * @option $version-history Use command history based on Drupal version
      *   (Default is per site).
-     * @option $cwd Changes the working directory of the shell
-     *   (Default is the project root directory)
+     * @option $cwd A directory to change to before launching the shell. Default is the project root directory
      * @topics docs:repl
      * @remote-tty
      */
-    public function cli(array $options = ['version-history' => false, 'cwd' => null])
+    public function cli(array $options = ['version-history' => false, 'cwd' => self::REQ])
     {
         $configuration = new Configuration();
 
@@ -82,7 +81,7 @@ public function cli(array $options = ['version-history' => false, 'cwd' => null]
         }
 
         // If the cwd option is passed, lets change the current working directory to wherever
-        // the user wants to go before we lift psysh.
+        // the user wants to go before we launch psysh.
         if ($options['cwd']) {
             chdir($options['cwd']);
         }