Specify scope options in same format as other arguments that have a list

[janw-me]

The current format was a bit confusing to me, what did "old" do? Was I it maybe a typo "old_tables"?
Found out there was a more conventional formatting listed options.

Based on the documentation of wpdb->tables().

Nowhere in the current codebase is there a list of options, that is then further clarified per option.
So I just did put in this format as "readable". I think the extra explanation is valuable in this case, as options aren't clear by themselves.

Point of discussion.
Is there a better way of doing the extra clarification, will this break auto documentation?
If there is a better way please point me to an example and I will follow it.

[github-actions]

Hello! 👋

Thanks for opening this pull request! Please check out our contributing guidelines. We appreciate you taking the initiative to contribute to this project.

Contributing isn't limited to just code. We encourage you to contribute in the way that best fits your abilities, by writing tutorials, giving a demo at your local meetup, helping other users with their support questions, or revising our documentation.

Here are some useful Composer commands to get you started:

• composer install: Install dependencies.
• composer test: Run the full test suite.
• composer phpcs: Check for code style violations.
• composer phpcbf: Automatically fix code style violations.
• composer phpunit: Run unit tests.
• composer behat: Run behavior-driven tests.

To run a single Behat test, you can use the following command:

# Run all tests in a single file
composer behat features/some-feature.feature

# Run only a specific scenario (where 123 is the line number of the "Scenario:" title)
composer behat features/some-feature.feature:123

You can find a list of all available Behat steps in our handbook.

[gemini-code-assist]

Code Review

This pull request updates the documentation for the --scope parameter in DB_Command.php to provide detailed descriptions for each available option. A critical issue was identified where including descriptions within the options list in the docblock breaks WP-CLI's argument validation and shell completion; the feedback suggests moving these descriptions to the main argument description section while keeping the options block as a simple list.

[gemini-code-assist]

Including descriptions directly within the options list in the docblock will break WP-CLI's argument validation and shell completion. The parser treats the entire line (including the description) as the valid option value. To fix this, move the descriptions to the argument's description section and keep the options block as a simple list of valid values.

	 * : List tables based on the scope.
	 *
	 * - all: returns 'all' and 'global' tables. No old tables are returned.
	 * - blog: returns the blog-level tables for the queried blog.
	 * - global: returns the global tables for the installation, returning multisite tables only on multisite.
	 * - ms_global: returns the multisite global tables, regardless if current installation is multisite.
	 * - old: returns tables which are deprecated.
	 * ---
	 * default: all
	 * options:
	 *   - all
	 *   - blog
	 *   - global
	 *   - ms_global
	 *   - old

[swissspidy]

Nowhere in the current codebase is there a list of options, that is then further clarified per option. So I just did put in this format as "readable". I think the extra explanation is valuable in this case, as options aren't clear by themselves.

Point of discussion. Is there a better way of doing the extra clarification, will this break auto documentation? If there is a better way please point me to an example and I will follow it.

Absolutely a great idea! We can add support in the doc parser in the framework and then it should work for documentation too.

At first glance, perhaps the extra clarification could be on a newline with some indentation. Then it could be even longer and multi-line if needed.

[swissspidy]

That said, the above Gemini suggestion also looks reasonable to me :)