代码示例样式指南

本文档介绍了如何将代码示例整合到文档中, 和具体的样式指南。其中包括:

有关常规文档标准(包括文件类型、位置和常规设置)的信息, 请参阅 Fuchsia 文档标准。 有关用词、样式和结构的具体指南,请参阅 Fuchsia 文档样式指南

代码示例最佳做法

针对您非常熟悉的 Fuchsia 部分创建代码示例时, 考虑新用户会如何阅读样本,并尝试预测他们的需求。 考虑整个流程,并包含完成该流程的必要步骤 并指明成功的标准

例如,在开始使用 Google Workspace 之前,请考虑以下必备信息: 示例代码请确保您没有忽视使用 示例,但不会再出现在您的日常工作流程中。

这可能是因为您已经执行了很多次这些步骤, 过程的必要性。也可能是因为 因此您只需填写一次前提条件信息 在撰写文档时无法回忆起这些步骤。如果可能,请尝试 从一开始就开始测试您的样本,并验证您是否具备所有前提条件 记录信息。

同样,请务必通知用户何时成功完成 正确执行这一给定过程。要提高用户对样本的置信度,请确保 应指定用户代码的外观以及用户如何确认 已成功运行您的示例。

代码示例核对清单

如果您要在文档中添加代码示例,请查看以下内容 列表,然后再提交您的贡献内容,以确保代码示例清晰明了:

  • 添加“前提条件”部分,也就是 文档。 在该套件中收集必备信息 文档,以免用户进入流程 以免遭到不必要的阻碍或沮丧。
    • 前提条件信息可包含以下任一项: <ph type="x-smartling-placeholder">
        </ph>
      • 修改环境变量。
      • 在启动过程之前运行必要的脚本。
      • 获取设备访问权限。
      • 包括 BUILD 依赖项。
      • 导入库。
  • 指向现有文档的链接(如果适用)。 例如,您要记录的流程的前提条件 可能是已铺路面的 Fuchsia 目标设备。 不要重申如何给某个人的设备铺路,而应链接到一个现有的 fuchsia.dev 上已存在的“铺路”主题, 例如 Build and pave quickstart
  • 如果您属于以下情况,请避免使用 foobar 或其他模糊的占位符名称 在代码示例中添加占位符 而应使用能够体现该占位符功能的名称 。如需了解详情,请参阅避免使用模糊的占位符
  • 通过陈述显而易见的事项,让开发者紧紧把握住整个流程。 预想到有人可能在没有仔细阅读完整内容的情况下运行了代码示例 文档。因此,请确保您的代码示例具有空间性。 。如需了解详情,请参阅指定展示位置
  • 在代码段的结尾处提供代码示例摘要,其中详细说明了 代码格式与程序中给定点的描述一致。 有关详情,请参阅指定展示位置确认成功
  • 说明测试流程所需的步骤并显示哪些是成功的 终端输出内容大致是这样的

代码示例样式指南

以下是创建易于理解的 请参阅文档中的代码示例

避免使用模糊的占位符

代码示例占位符名称和值应在 避免使用 foobar 等抽象占位符。

  • 使用占位符名称来表达占位符的功能 代码。 这样做可以为开发者提供一个真实示例,供其参考 。

  • 应能够将代码示例复制到终端并运行 无需用户进行大量更改即可成功加载

请参阅以下示例,了解如何避免含糊不清的占位符。

示例

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
</ph>

如需添加服务,请添加以下代码:

protocol: "fuchsia.example.Foo"

。 <ph type="x-smartling-placeholder">
</ph>

要添加服务,您必须修改组件清单 (.cml)。 例如,添加 fuchsia.process.Launcher service 添加到组件清单中,该组件就能够启动 过程。

  use: [
    {
      protocol: "fuchsia.process.Launcher"
    }
  ]

指定展示位置

代码示例应指定该代码应放置于何处 位于指定文件内。

例如,如果某行代码应位于特定函数内, 那么代码示例应该展示空间顺序,而不是 在没有上下文的情况下显示代码行。

请参阅有关指定代码位置的示例。

示例

<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
</ph>

添加以下内容:

syslog::fx_log_info!("{}, log!", greeting());

。 <ph type="x-smartling-placeholder">
</ph>

将日志消息添加到源文件中 为 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">
</ph> <ph type="x-smartling-placeholder">
</ph>

添加上述代码即表示您已启用 Fuchsia 的登录功能。

。 <ph type="x-smartling-placeholder">
</ph>

至此,您已启用 Fuchsia 的登录功能。 要确认已在组件中启用日志记录,请完成 操作步骤:

  1. 确保 fx serve 在 shell 标签页中运行。如果不是,请打开一个 shell Tab 键并运行 fx serve
  2. cd ~/fuchsia

    fx serve

  3. 在新 shell 标签页中,导航到 fuchsia 目录并运行 ffx log
  4. cd ~/fuchsia

    ffx log

  5. 在新 shell 标签页中,导航到 fuchsia 目录,然后运行 hello_world_rust 组件:
  6. cd ~/fuchsia

    ffx component run /core/ffx-laboratory:hello-world fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm

  7. 前往您运行 ffx log 的 shell 标签页。
  8. 您应该能够看到日志记录文本,在此示例中 为 Hello log!