文档指南 - MRTK2

  • 项目
MRTK

本文档概述了混合现实工具包 (MRTK) 的文档准则和标准。 介绍了文档编写和生成的技术方面，重点介绍了常见的易犯错误，并描述了建议的编写风格。

页面本身应作为示例，因此它使用文档的预期样式和最常见的标记功能。

功能和标记

本节介绍经常需要的功能。 若要查看其工作原理，请查看页面的源代码。

  1. 编号列表
    1. 带有至少三个前导空格的嵌套编号列表
    2. 代码中的实际编号是不相关的；解析将负责设置正确的项目编号。
  • 项目符号点列表
    • 嵌套项目符号点列表
  • 带 **双星号** 的粗体文本
  • 带 _underscore_ 或 *单星号* 的斜体文本
  • 使用`反引号`的句内文本 highlighted as code
  • 链接到文档页面 MRTK 文档准则
  • 链接到页中的定位点；通过用短划线替换空格并将其转换为小写来形成定位点

对于代码示例，我们使用三个带有反撇号 ``` 的块，并指定 csharp 作为语法突出显示的语言：

int SampleFunction(int i)
{
   return i + 42;
}

当涉及句子中的代码时，use a single backtick。

Todo

避免在文档中使用 Todo，因为随着时间的推移，这些 Todo（如代码 Todo）往往会积累，以及关于它们应该如何更新和为何会丢失的信息。

如果绝对需要添加 TODO，请遵循以下步骤：

  1. 在 Github 上提交一个新问题，描述 TODO 背后的上下文，并提供足够的背景，使另一参与者能够理解并解决 TODO。
  2. 参考文档中 todo 的问题 URL。

<!-- TODOhttps://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE：问题的简短介绍-->

突出显示的部分

若要向读者突出显示特定点，请使用 > [!注意]、> [!警告] 和 > [!重要] 来生成以下样式。 建议仅在特殊相关情况下，对一般要点和警告/重要要点使用注释。

注意

注释示例

警告

警告示例

重要

重要注释示例

页面布局

介绍

主要章节标题后的部分应作为本章内容的简短介绍。 不要将其设置得太长，而应添加子标题。 它们允许链接到各部分，并可以保存为书签。

主体

使用两级和三级标题来构建其余内容。

迷你部分

为应突出显示的块使用粗体文本。在某些时候，我们可能会将此替换为四级标题。

“另请参阅”部分

大多数页面都应以名为“另请参阅”的部分结束。 本章只是指向与本主题相关的页面的链接列表。 这些链接也可能出现在页面文本中相应的位置，但这不是必需的。 同样，页面文本可能包含指向与主要主题不相关的页面的链接，这些链接不应包含在“另请参阅”列表中。 有关链接选择的示例，请参阅此页的“另请参阅”一章。

目录 (TOC)

Toc 文件用于在 MRTK github.io 文档中生成导航栏。 添加新的文档文件时，请确保文档文件夹的一个 toc.yml 文件中存在该文件的条目。 只有 toc 文件中列出的项目才会显示在开发人员文档的导航中。文档文件夹中的每个子文件夹都可以有一个 toc 文件，该文件可链接到任何现有的 toc 文件，以将其作为子部分添加到导航的相应部分。

样式

写入样式

一般经验法则：尽量“听起来专业”。 这通常意味着避免使用“交谈语气”。 还要尽量避免夸张和哗众取宠。

  1. 不要试图（过度）搞笑。
  2. 从不写“我”
  3. 避免使用“我们”。 这通常可以使用“MRTK”轻松地改写。 示例：“我们支持此功能” ->“MRTK 支持此功能”或“支持以下功能…”。
  4. 同样，尽量避免使用“你”。 示例：“通过此简单更改，你的着色器将变得可配置！”->“可轻松使着色器变得可配置。”
  5. 不要使用“草率短语”。
  6. 避免听起来太兴奋，我们不需要进行任何销售。
  7. 同样，避免过度戏剧化。 很少需要使用感叹号。

大写

  • 对标题使用句子首字母大写。即首字母和名称的首字母大写，其他内容则不用。
  • 对于其他所有内容，请使用常规英语。 这意味着不要随意使用大写单词，即使它们在该上下文中具有特殊含义。 首选通过斜体文本突出显示某些字词，请参阅下文。
  • 当在句子中嵌入链接时（这是首选方法），标准章节名称始终使用大写字母，从而打破了文本内部不能随意大写的规则。 因此，请使用自定义链接名称来修复此大写。 例如，下面是指向边界控制文档的链接。
  • 大写名称（例如 Unity）。
  • 写“Unity editor”时，不要大写“editor”。

强调和突出显示

可以通过两种方式强调或突出显示字词，即使用粗体或斜体。 粗体文本的效果是粗体文本突出，因此在浏览一段文本或甚至只是滚动页面时，可以很容易地注意到。 粗体非常适合突出显示应该记住的短语。 但请少用粗体文本，因为这通常会分散注意力。

通常，人们希望将逻辑上属于同类的事物“分组”或突出显示特定术语，因为它具有特殊含义。 这些内容不需要在整个文本中突出。 使用斜体文本作为轻量级方法来突出显示某些内容。

同样，如果在文本中提到了文件名、路径或菜单项，则首选将其设置为斜体以便对其进行逻辑分组，而不会分散注意力。

通常，请尽量避免不必要的文本突出显示。 特殊术语可以突出显示一次以使读者知道，但不要在整个文本中重复此类突出显示，因为它不再起作用，只会分散注意力。

提及菜单项

提及用户应该单击的菜单项时，当前约定为：“项目”>“文件”>“创建”>“叶”

尽可能多地插入其他页面的有用链接，但每个链接只需一次。 假设一个读者会单击页面上的每个链接，想象一下，如果同一个页面打开了 20 次，这会是多么烦人。

首选句子中嵌入的链接：

  • 不好：准则很有用。 有关详细信息，请参阅此章节。
  • 好：准则很有用。

避免使用外部链接，它们可能会过时或包含版权内容。

添加链接时，请考虑是否还应该在另请参阅部分中列出。 同样，请检查是否应将指向新页的链接添加到“链接到”页中。

图像/屏幕截图

请慎用屏幕截图。 维护文档中的图像是一项繁重的工作，小小的 UI 更改可能会使大量屏幕截图过时。 以下规则将减少维护工作量：

  1. 不要将屏幕截图用于可在文本中描述的内容。 特别是，切勿仅出于显示属性名称和值的目的制作属性网格的屏幕截图。
  2. 不要在屏幕截图中包括与显示内容无关的内容。 例如，显示呈现效果时，制作视区的屏幕截图，但排除其周围的任何 UI。 在显示一些 UI 时，尝试移动窗口，使图像中只有重要部分。
  3. 包括屏幕截图 UI 时，仅显示重要部分。 例如，在讨论工具栏中的按钮时，请创建一个显示重要工具栏按钮的小图像，但是排除它周围的所有内容。
  4. 仅使用容易重现的图像。 这意味着不要在屏幕截图中绘制标记或突出显示内容。 首先，无论如何，并没有一致的规则来规定这些内容应该看起来如何。 其次，重现此类屏幕截图会增加工作量。 相反，请在文本中描述重要部分。 此规则有例外，但很少发生。
  5. 很明显，重新创建动画 GIF 的工作量要大得多。 指望花无尽的时间负责重新创建它，或者如果不想花费这个时间，则指望放弃它。
  6. 尽量减少文章中的图像数量。 通常，一种很好的方法是为某个工具制作一个整体的屏幕截图，其中显示所有内容，然后在文本中描述其余内容。 这样就可以在需要时轻松替换屏幕截图。

其他一些方面：

  • 用于屏幕截图的编辑器 UI 应使用浅灰色主题编辑器，因为并非所有用户都有权使用深色主题，我们希望尽可能使其保持一致。
  • 默认图像宽度为 500 像素，因为这在大多数监视器上显示良好。 尽量不要偏离此数值太多。800 像素宽度应为最大值。
  • 为 UI 的屏幕截图使用 PNG。
  • 为 3D 视区屏幕截图使用 PNG 或 JPG。 质量比压缩比更重要。

组件属性列表

记录属性列表时，请使用粗体文本突出显示属性名称，然后使用换行符和常规文本对其进行描述。 不要使用子章节或项目点符号列表。

此外，请不要忘记以句点结束所有句子。

页面完成清单

  1. 确保遵循本文档的准则。
  2. 浏览文档结构，并查看是否可以在其他页面的另请参阅部分下提及新文档。
  3. 如果可以，请让了解该主题的人员校对页面以确保技术正确性。
  4. 让他人对页面的样式和格式进行校对。 这可以是不熟悉该主题的人，这也是一个获得文档可理解性反馈的好主意。

源文档

将从 MRTK 源文件中自动生成 API 文档。 为了便于实现此操作，源文件需要包含以下内容：

除了上述内容外，还应对代码进行很好的注释，以便进行维护、bug 修复和简化自定义。

类、结构、枚举摘要块

如果要将类、结构或枚举添加到 MRTK 中，则必须对其目的进行说明。 这将采用类之上的摘要块的形式。

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

如果有任何类级别的依赖项，它们应该记录在备注块中，紧靠在摘要的下方。

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

未提供类、结构或枚举摘要的拉取请求将不予批准。

属性、方法、事件摘要块

属性、方法和事件 (PME) 以及字段将与摘要块一起记录，而不考虑（公共、私有、受保护和内部）的代码可见性。 文档生成工具负责仅筛选和发布公共和受保护的功能。

注意：Unity 方法不需要摘要块（例如：唤醒、启动、更新）。

需要 PME 文档才能批准拉取请求。

作为 PME 摘要块的一部分，需要使用参数的含义和用途以及返回的数据。

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

功能简介版本和依赖关系

作为 API 摘要文档的一部分，有关引入此功能的 MRTK 版本的信息以及所有依赖项都应记录在备注块中。

依赖项应包括扩展和/或平台依赖项。

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

序列化字段

使用 Unity 的工具提示属性为检查器中的脚本字段提供运行时文档是一种很好的做法。

为了使配置选项包含在 API 文档中，脚本需要至少在摘要块中包含工具提示内容。

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

枚举值

在定义和枚举时，代码还必须使用摘要块记录枚举值的含义。 可以选择使用备注块来提供更多详细信息以增强理解。

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

操作说明文档

许多混合现实工具包的用户可能不需要使用 API 文档。 这些用户将利用我们预先制作的、可重复使用的预制件和脚本来创建自己的体验。

每个功能区域都将包含一个或多个 markdown (.md) 文件，这些文件在相当高的级别上描述所提供的内容。 根据给定功能区域的大小和/或复杂性，可能需要其他文件，每个功能最多有一个。

添加功能（或更改用法）时，必须提供概述文档。

作为本文档的一部分，应提供操作方法部分（包括插图）以帮助不熟悉功能或概念的客户开始使用。

设计文档

混合现实为创建全新的世界提供了机会。 部分内容可能涉及创建自定义资产，以便与 MRTK 一起使用。 为了使客户尽可能无障碍，组件应提供描述艺术资产的任何格式或其他要求的设计文档。

设计文档可能有帮助的一些示例：

  • 光标模型
  • 空间映射可视化效果
  • 声音效果文件

强烈建议使用这种类型的文档，并且可能会在拉取请求评审过程中请求此类文档。

这不一定与 MS 开发人员网站上的设计建议有所不同

性能说明

一些重要的功能以性能为代价。 通常，此代码将非常依赖于其配置方式。

例如：

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

建议对 CPU 和/或 GPU 繁重的组件使用性能注释，并且可能会在拉取请求评审过程中请求此类文档。 任何适用的性能注释都包含在 API 和概述文档中。

中断性变更

重大更改文档由顶级文件组成，该文件链接到每个功能区的单个 breaking-changes.md。

功能区 breaking-changes.md 文件包含给定版本的所有已知重大更改的列表以及过去版本的重大更改的历史记录。

例如：

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

功能级别 breaking-changes.md 文件中包含的信息将聚合到每个新 MRTK 版本的发行说明中。

任何属于更改的重大更改都必须记录为拉取请求的一部分。

用于编辑 MarkDown 的工具

Visual Studio Code 是一种很好的工具，用于编辑 MRTK 文档中的 markdown 文件。

编写文档时，还强烈建议安装以下两个扩展：

  • Visual Studio Code 的文档 Markdown 扩展 - 按 Alt+M 即可调出文档创作选项菜单。

  • 代码拼写检查器 - 拼错的单词带有下划线；右键单击拼错的单词可进行更改或将其保存到字典中。

这两个扩展都打包在 Microsoft 发布的文档创作包中。

另请参阅