代码即文档？介绍Cargo spec

Posted 2022-03-30 mutourend

1. 引言

在 David Wong 2022年3月博客The code is the specification? Introducing cargo spec 中，介绍了其在Kimchi项目中使用的cargo-spec工具。

2. 说明文档很重要

大多数在用的密码学方案都应附有详细的规范说明文档，类似于RFC，但RFC并不是唯一的标准。

说明文档具有多重目的：

• 1）用于帮助他人实现某算法或协议。这通常是RFC的目的。
• 2）用于帮助他人理解某协议的工作原理。在仅有代码的情况下，若想要理解某协议，将需要对该代码进行反向工程。并不是每个人都擅长反向工程。也并不是所有人都能或者有时间阅读协议中的代码。

若没有说明文档：

• 当研究人员分析某协议时，并不知道该协议的工作原理，研究人员也不想阅读大量的Rust代码来分析；
• 当安全工程师review bugs时，若没有说明文档，如何定义何为bug？若没有描述协议的高层文档，你无法理解协议的逻辑。

当有说明文档时，安全工程师仅需要将文档与代码匹配，任何偏离即为bug。

3. 代码即文档

写代码应像写书，其会被他人反复阅读、修改和维护。

一本书有章节、介绍、出处、标注等。为什么代码不应该有相同的内容？代码已经有了：文件、模块、包、命名空间、函数名、变量名、注释等都是开发人员可以用来让代码可读的技巧。但这并不意味着你不能在代码中增加实际的章节。推荐观看Timothy Daly的Literate Programming in the Large。
在Timothy的视频中，其观点为：

• 本人是文档的第一用户；
• 我们可能会在某时忘记缩写的代码，但是文档将大有帮助。若没有文档，代码修改将是艰巨的任务。
  Timothy的观点是为你的代码写一本书，且没有理由不写。

4. 如何编写文档？

过去，人总是将文档独立于代码库。但是，当你使用自制协议处理项目时，通常有一个参考实现。该参考实现是活跃的，它会随着时间的推移而变化。这意味着，动态项目的文档往往与实现有所不同，除非它们由严格的开发人员维护。

另一个方案是在代码中写文档，可由开发者在调整代码时维护更新。但是文档通常是结构化的，具有介绍、处处、标注、概述等等，并不适于将其切分为多个文件。——使用cargo-spec。

4.1 使用Cargo-spec来编写文档

cargo-spec工具由Rust语言实现，但其可用于任意语言的代码库中。

cargo-spec工具要求具有2个模块：

• 1）一个模板 template.md。在该模板中包含以markdown记录了你文档的组织。你可在那填写内容，但需要填充部分代码时，可使用占位符。
• 2）一个说明配置文件 Specification.toml。帮助你列出要在文档中使用的代码位置。

该工具可从代码中提取内容，将其替换到占位符中，并生成最终的说明书（目前支持2种格式：markdown和respec）。

在Kimchi中，使用mdbook来服务，在mdbook中包含了LaTeX方程式。也可使用hugo或其它工具。也可以纯markdown形式编写。

从代码中提取的内容是？注释具有特殊前缀（//~ Rust 或@~ Python 或 (*~...*) OCaml等）。

4.2 Rustdoc vs spec doc

若对特定的Rust代码不感兴趣，可忽略该章节。

Rust默认支持2种注释类型：

• 常规注释：//
• 文档注释：///、//!、/**...*/。

然后可运行cargo run，相应的文档注释会被解析并生成一个html文档。

既然不能同时使用spec注释和文档注释，那么如何协调两者呢？cargo spec的理念是，应该使用语言文档注释来指定代码的接口；而不是内在逻辑。因此，文档应将代码库当成黑河。因为谁使用文档？希望使用该库而不必了解其内部内容的开发人员。

另一方面，维护者、贡献者和审核人等将关注库的内容，可用spec注释来实现说明。

4.3 举例

cargo-spec的说明文档本身是用cargo spec自身来编写的。该工具的一个简单示例可参看：

• https://mimoo.github.io/cargo-specification/

参考资料

[1] David Wong博客The code is the specification? Introducing cargo spec