在编写 Orchestrator 插件的用户界面 (UI) 字符串和相关 API 的文档时,请遵循以下广受认可的样式和格式规则。

常规建议

  • 若插件中涉及 VMware 产品,请使用其官方名称。例如,使用以下产品的官方名称和 VMware 术语。

    正确术语

    请勿使用

    vCenter Server

    VC 或 vCenter

    vCloud Director

    vCloud

  • 每句工作流描述都以句点结尾。例如,Creates a new Organization. 是一句工作流描述。

  • 使用文本编辑器和拼写检查器来编写描述,然后将其移至插件。

  • 确保插件名称完全匹配所关联第三方产品已批准的名称。

工作流和操作

  • 编写信息性描述。大多数操作和工作流只需一两个句子即可。

  • 较高级别工作流可能要包含更宽泛的描述和备注。

  • 编写描述时直接以动词开头,例如:Creates…。不要使用自引用语言,例如 This workflow creates

  • 在句子完整的描述结尾使用句点。

  • 描述工作流或操作有何用处而不是如何实现。

  • 工作流和操作通常随附在文件夹和软件包中。同时也随附了这些文件夹和软件包的简短描述。例如,工作流文件夹的描述可类似 Set of workflows related to vApp Template management

工作流和操作的参数

  • 使用描述性的名词短语(例如 Name of)作为工作流和操作描述的开头。请勿使用诸如 It's the name of 等短语。

  • 请勿在参数和操作描述的结尾添加句点。这些不是完整的句子。

  • 工作流的输入参数必须指定标签,在展示视图中包含相应名称。在许多情况下,您可以合并显示组中的相关输入。例如,您可以创建标签为“组织”的显示组并将名称和完整名称输入放置在“组织”组内,而不是分别为两种输入内容创建“组织名称”和“组织全名”标签。

  • 对于步骤和显示组,还将添加工作流展示中显示的描述或备注。

插件 API

  • API 文档指 vso.xml 文件和 Java 源文件中的所有文档。

  • 对于 vso.xml 文件,查找器对象和脚本对象的描述采用与工作流和操作描述相同的规则。对象属性和方法参数的描述采用与工作流和操作参数描述相同的规则。

  • 避免在 vso.xml 文件中使用特殊字符,并且需要在 <![CDATA[insert your description here!]]> 标记中包含描述。

  • 对 Java 源文件使用标准 Javadoc 样式。