代码即文档?介绍Cargo spec

Posted mutourend

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了代码即文档?介绍Cargo spec相关的知识,希望对你有一定的参考价值。

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自身来编写的。该工具的一个简单示例可参看:

参考资料

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

以上是关于代码即文档?介绍Cargo spec的主要内容,如果未能解决你的问题,请参考以下文章

Rust: Cargo 使用本地 crate

Cargo使用文档-指定依赖项

同步FIFO设计Spec

Rust Rustup cargo配置国内镜像源

actix rust actor 框架学习 二 ping actor demo 代码

Maven2:Cargo 插件热部署 & Jonas 支持