Cargo spec  

这是一个将您的代码转换为规范的工具。它是语言无关的，但您需要Cargo（您可以通过Rustup安装）来使用它。要查看它的实际效果，只需查看此代码库中的代码，以及产生的规范。您可以在《代码即规范：介绍cargo-spec》博客文章中了解更多关于其背后的概念。

使用方法

initialize. 要开始您的规范，您需要两个文件：一个Specification.toml配置文件和一个包含您用Markdown编写的规范模板。您可以通过在当前目录下运行cargo spec new <NAME>或通过在指定路径上运行cargo spec init <PATH>来创建这些文件。

$ cargo install cargo-spec
$ cargo spec new

Created new specification as Specification.toml and specification_template.md
You can now run `cargo spec build` to create the specification file

build. 构建您的规范将把您的模板转换为所需的格式（默认为Markdown），并在某个路径下（默认为specification.md）

$ cargo spec build

=> html output saved at ./specification.md

您还可以监视任何更改

$ cargo spec watch

=> html output saved at ./specification.md

如何编写规范？

cargo-spec的哲学源于这样一个事实：大多数协议通常来自参考实现。这个参考实现往往会发生变化，而您希望规范是最新的，因此您会希望将规范的部分尽可能接近代码。

cargo-spec允许您将规范编写为Markdown文件，并从您的代码中提取特殊的“规范注释”来填充规范的部分。

配置

要运行 cargo-spec，您需要一个 Specification.toml 文件。虽然您可以通过 --specification-path 选项指定不同的文件名。

[specification]
# some metadata
name = "Consensus"
description = "This specification describes the consensus protocol."
version = "0.1.0"
authors = ["David Wong"]

[config]
# the path to your template
template = "template.md"

[sections]
# all the files you want to extract "spec comments" from
data_structures = "src/data_structures.rs"
abstract_modules = "@/src/module.rs" # you can also use absolute paths (you need to be in a git repo)

模板

模板实际上是一个包含占位符的 markdown 文件。模板的路径必须在 Specification.toml 文件中指定。默认情况下，cargo spec new <NAME> （或 cargo spec init <PATH>） 命令将使用 specification_template.md 作为模板。

# Consensus specification

Here's the consensus spec

## Data structures

{sections.data_structures}

## Abstract modules

{sections.abstract_modules}

代码中的 Spec 注释

Cargo-spec 识别以波浪号 ~ 开头的注释。例如，在 Rust 中

//~ some specification text

在 Python 中

#~ here's some spec

或在 OCaml 中

(*~ some spec *)

尽管 cargo-spec 对语言无特定要求，但它不支持所有类型的注释。如果您使用的语言不支持，请 提交问题。

嵌套列表

手动缩进注释以创建嵌套列表可能会很累人

//~ - a list
//~   - a nested list

相反，只需在 spec 注释的开头添加 ~ 以添加缩进

//~ - a list
//~~ - a nested list

导入代码

您可以通过将它们包围在 //~ spec:startcode 和 //~ spec:endcode 之间来导入代码块

//~ spec:startcode
struct SomeStruct {
  a: u8,
  b: u64,
}
//~ spec:endcode

持续集成

您可能希望强制要求 PR 包含已签入的更新规范文件。例如，您可以使用此 Github Action 来实现此功能

name: Check specifications

on:
  pull_request:

jobs:
  run_checks:
    runs-on: ubuntu-latest
    name: Enforce up-to-date specification files
    steps:

      - name: Checkout PR
        uses: actions/checkout@v2

      - name: Set up cargo/rust
        uses: actions-rs/toolchain@v1

      - name: Check that up-to-date specification is checked in
        run: |
          cargo install cargo-spec
          cd <spec_folder>
          cargo spec build
          git diff --exit-code

使用 cargo-spec 的项目

• cargo-spec (spec)
• kimchi (spec)

许可协议

Cargo spec 项目根据 Apache 2.0 和 MIT 条款双许可。有关详细信息，请参阅 LICENSE-APACHE 和 LICENSE-MIT。