文档标准

为了促进WP-CLI命令之间的相似性和一致性，我们制定了这些文档标准，我们鼓励您遵循。通用性是可用性的关键组成部分，因为它减少了在命令之间切换时所需的心理开销。

针对 WP-CLI 项目的拉取请求将针对这些标准进行审查。请为您的自定义命令也遵循这些标准。

命令注释

下面是 PHPdoc 注释命令的示例：wp cron event schedule

/**
 * Schedule a new cron event.
 *
 * ## OPTIONS
 *
 * <hook>
 * : The hook name.
 *
 * [<next-run>]
 * : A Unix timestamp or an English textual datetime description compatible with `strtotime()`. Defaults to now.
 *
 * [<recurrence>]
 * : How often the event should recur. See `wp cron schedule list` for available schedule names. Defaults to no recurrence.
 *
 * [--<field>=<value>]
 * : Associative args for the event.
 *
 * ## EXAMPLES
 *
 *     # Schedule a new cron event.
 *     $ wp cron event schedule cron_test
 *     Success: Scheduled event with hook 'cron_test' for 2016-05-31 10:19:16 GMT.
 *
 *     # Schedule new cron event with hourly recurrence.
 *     $ wp cron event schedule cron_test now hourly
 *     Success: Scheduled event with hook 'cron_test' for 2016-05-31 10:20:32 GMT.
 *
 *     # Schedule new cron event and pass associative arguments.
 *     $ wp cron event schedule cron_test '+1 hour' --foo=1 --bar=2
 *     Success: Scheduled event with hook 'cron_test' for 2016-05-31 11:21:35 GMT.
 */

要逐个分解示例：

  • “安排新的 cron 事件”是命令描述。命令描述应少于 50 个字符，并以活动时态、现在时书写。
  • 选项部分应以 开头。在标题前后保留一个空行。## OPTIONS
  • 每个选项的命名方式应简明扼要地描述其用途。
  • 示例部分应以 开头。在标题前后保留一个空行。## EXAMPLES
  • 在每个示例之前和之后包含一个空行，以帮助直观地将每个示例指示为单独的示例。
  • 每个示例应包含 3 个部分。
    • 描述
      • 必须以 和空格开头。#
      • 句子应以大写字母开头。
      • 注释必须以句号、感叹号或问号结尾。
      • 例如：# Create database.
    • 命令
      • 必须以 和空格开头。例如：$``$ wp db create
    • 示例输出
      • 保持准确的输出。注意输出中的空格和缩进。例外：如果输出很长，则可以将其截断以仅显示合适的部分。
      • 例如：Success: Database created.
  • 如果可能，请为每个命令至少保留两个示例。一个显示基本用途，另一个显示高级用途。用例越多越好。

有关WP-CLI如何理解PHPdoc的更多详细信息，请参阅命令说明书。

类注释

对于表示子命令集合的类，我们鼓励您使用类级注释来提供集合的介绍。

/**
 * Manage options.
 *
 * ## EXAMPLES
 *
 *     # Get site URL.
 *     $ wp option get siteurl
 *     http://example.com
 *
 *     # Add option.
 *     $ wp option add my_option foobar
 *     Success: Added 'my_option' option.
 *
 *     # Update option.
 *     $ wp option update my_option '{"foo": "bar"}' --format=json
 *     Success: Updated 'my_option' option.
 *
 *     # Delete option.
 *     $ wp option delete my_option
 *     Success: Deleted 'my_option' option.
 */
  • 类可以有多个示例。请遵循命令文档示例的标准。

命令执行中的消息

$ wp theme activate twentysixteen
Success: Switched to 'Twenty Sixteen' theme.
  • 邮件必须以大写字母开头。
    • 例外：当消息以特殊键开头并用引号括起来时。例如 –'movie' is not a registered post type.
  • 如果是单行消息，则必须以 结尾。.
    • 例外：像这样使用冒号时，末尾不应有尾随字符。:``Invalid ID: 123
    • 例外：要在进度条中显示的消息可以省略尾随句点。例如 –Generating comments
  • 文件名和文件夹名称必须用引号 （ ） 括起来。'
  • 角色、侧边栏 ID、帖子类型键、分类键必须用引号括起来。
  • 正在进行的操作上下文中的消息可能以 结尾。例如 – '从 https://github.com/wp-cli/wp-cli/releases/download/v0.23.1/wp-cli-0.23.1.phar&#8230 下载...;`

命令参数说明

如果命令参数有一组允许的值，我们为默认值和可用选项设置了特殊格式（通常类似于 YAML）。

[--format=<format>]
: Render output in a particular format.
---
default: table
options:
  - table
  - csv
  - json
  - count
  - yaml
---
  • 部分以参数描述旁边的单独行开头。---
  • 在下一行中，使用 保留默认值。default: value
  • 对于选项，请从以下行开始。options:
  • 将值保留在以下模式中：2 个空格、、1 个空格、值-
  • 用 关闭部分。---