本文档介绍了如何将代码示例整合到文档中, 和具体的样式指南。其中包括:
有关常规文档标准(包括文件类型、位置和常规设置)的信息, 请参阅 Fuchsia 文档标准。 有关用词、样式和结构的具体指南,请参阅 Fuchsia 文档样式指南。
代码示例最佳做法
针对您非常熟悉的 Fuchsia 部分创建代码示例时, 考虑新用户会如何阅读样本,并尝试预测他们的需求。 考虑整个流程,并包含完成该流程的必要步骤 并指明成功的标准
例如,在开始使用 Google Workspace 之前,请考虑以下必备信息: 示例代码请确保您没有忽视使用 示例,但不会再出现在您的日常工作流程中。
这可能是因为您已经执行了很多次这些步骤, 过程的必要性。也可能是因为 因此您只需填写一次前提条件信息 在撰写文档时无法回忆起这些步骤。如果可能,请尝试 从一开始就开始测试您的样本,并验证您是否具备所有前提条件 记录信息。
同样,请务必通知用户何时成功完成 正确执行这一给定过程。要提高用户对样本的置信度,请确保 应指定用户代码的外观以及用户如何确认 已成功运行您的示例。
代码示例核对清单
如果您要在文档中添加代码示例,请查看以下内容 列表,然后再提交您的贡献内容,以确保代码示例清晰明了:
- 添加“前提条件”部分,也就是
文档。
在该套件中收集必备信息
文档,以免用户进入流程
以免遭到不必要的阻碍或沮丧。
- 前提条件信息可包含以下任一项:
<ph type="x-smartling-placeholder">
- </ph>
- 修改环境变量。
- 在启动过程之前运行必要的脚本。
- 获取设备访问权限。
- 包括
BUILD
依赖项。 - 导入库。
- 前提条件信息可包含以下任一项:
<ph type="x-smartling-placeholder">
- 指向现有文档的链接(如果适用)。 例如,您要记录的流程的前提条件 可能是已铺路面的 Fuchsia 目标设备。 不要重申如何给某个人的设备铺路,而应链接到一个现有的 fuchsia.dev 上已存在的“铺路”主题, 例如 Build and pave quickstart。
- 如果您属于以下情况,请避免使用
foo
、bar
或其他模糊的占位符名称 在代码示例中添加占位符 而应使用能够体现该占位符功能的名称 。如需了解详情,请参阅避免使用模糊的占位符。 - 通过陈述显而易见的事项,让开发者紧紧把握住整个流程。 预想到有人可能在没有仔细阅读完整内容的情况下运行了代码示例 文档。因此,请确保您的代码示例具有空间性。 。如需了解详情,请参阅指定展示位置。
- 在代码段的结尾处提供代码示例摘要,其中详细说明了 代码格式与程序中给定点的描述一致。 有关详情,请参阅指定展示位置 和确认成功。
- 说明测试流程所需的步骤并显示哪些是成功的 终端输出内容大致是这样的
代码示例样式指南
以下是创建易于理解的 请参阅文档中的代码示例
避免使用模糊的占位符
代码示例占位符名称和值应在
避免使用 foo
和 bar
等抽象占位符。
使用占位符名称来表达占位符的功能 代码。 这样做可以为开发者提供一个真实示例,供其参考 。
应能够将代码示例复制到终端并运行 无需用户进行大量更改即可成功加载
请参阅以下示例,了解如何避免含糊不清的占位符。
示例
<ph type="x-smartling-placeholder">如需添加服务,请添加以下代码:
protocol: "fuchsia.example.Foo"
要添加服务,您必须修改组件清单 (.cml)。
例如,添加 fuchsia.process.Launcher
service
添加到组件清单中,该组件就能够启动
过程。
use: [ { protocol: "fuchsia.process.Launcher" } ]
指定展示位置
代码示例应指定该代码应放置于何处 位于指定文件内。
例如,如果某行代码应位于特定函数内, 那么代码示例应该展示空间顺序,而不是 在没有上下文的情况下显示代码行。
请参阅有关指定代码位置的示例。
示例
<ph type="x-smartling-placeholder">
添加以下内容:
syslog::fx_log_info!("{}, log!", greeting());
将日志消息添加到源文件中
为 main.rs
:
syslog::fx_log_info!("{}, log!", greeting());
此时,main.rs
应如下所示:
use fuchsia_syslog as syslog; fn main() { syslog::init().expect("should not fail"); syslog::fx_log_info!("{}, log!", greeting()); println!("{}, world!", greeting()); } …
确认成功
作为用户,当您不熟悉新流程时 即使您已经 已完成记录的所有步骤。
在方法指南中添加一个部分,说明开发者如何确认 他们已成功实施了相应的流程。如果可能的话 包含预期结果的终端输出。这样做有助于提高 提升用户信心
请参阅以下示例,了解如何在代码示例中确认成功。
示例
<ph type="x-smartling-placeholder">添加上述代码即表示您已启用 Fuchsia 的登录功能。
至此,您已启用 Fuchsia 的登录功能。 要确认已在组件中启用日志记录,请完成 操作步骤:
- 确保
fx serve
在 shell 标签页中运行。如果不是,请打开一个 shell Tab 键并运行fx serve
。 - 在新 shell 标签页中,导航到
fuchsia
目录并运行ffx log
。 - 在新 shell 标签页中,导航到 fuchsia 目录,然后运行
hello_world_rust
组件: - 前往您运行
ffx log
的 shell 标签页。
cd ~/fuchsia
fx serve
cd ~/fuchsia
ffx log
cd ~/fuchsia
ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
您应该能够看到日志记录文本,在此示例中
为 Hello log!
。