API 库的文档体系支持:主流编程语言的文档设计

去年,我们在那篇《编程语言的 IDE 支持》详细讨论了在不同 IDE、编辑器里,它们是如何提供对于编程语言的支持。在这一篇文章里,我们将不那么详细地讨论一下:不同的编程语言如何提供文档支持?如此一来,也能在未来为 Datum Lang 提供相关的理论体系支持。这里所指的编程语言的文档体系,主要是指语言标准库中的文档

新一代编程语言的文档体系

作为一个程序员,和诸多人一样,我并不热衷于在代码中写文档/注释。只是呢,诸多的情况下,我们依旧不得不写文档,如编程语言的标准库、API、SDK 等。在各个语言中,它们有各自不同的实践,有各自不同的特点。

起先,我只分析过 Rust 语言中的 rustdoc,分析它是如何自动化处理相关文档的。后来,联想到了其它语言的文档形式是不是也会类似。接着,便尝试性的整理自 2012 年后“比较”(相对,至少是我听得多的)主流的语言的文档方式。

于是,便花了点时间,从相关的代码库中快速梳理而来。因时间有限,加之不擅长某些语言。所以,结论上的可能并不是这么完整,欢迎各位读者指正。

d7b1437d6aa06f0b4d528f212205f5a5.png

从文档编写方式上来看,Rust、Julia、Dart、Kotlin、Swift 的文档工具都是相似的:基于 markdown 语法的基础上,进行了一系列的定制。如 Swift 文档中添加的一些特别的标准,如关于复杂度( Complexity)的特别说明,便使用了类似的方式来实现。而像 Julia 语言里的 DocumenterTools 则做了大量的定制,则可以基于 index.md 对内容进行特别处理,并添加大量的自定义语法。

从文档代码一致性上来看,从我初步阅读代码的情况来看,Rust、Julia 的文档工具都会校验文档中的代码是不是正常的,并能对其进行测试。如 Rustdoc 会编译、运行文档中的代码,可以通过 Rust 自身提供的断言语法(如 assert_eq!)进行测试。而像 Julia 里的 DocumenterTools 则做了更多的定制,如可以为文档添加 setup 方法,还能进行一系列相关的断言等。

除此,在 R 语言中提供的 R Markdown 也比较有意思,它提供了一种可执行文档的新思路,即让 markdown 与代码有机的结合在一起,结合 pandoc 构建了新的文档可能性。后续,可能会在文档体验设计相关的文章中,进行详细的介绍。

Rust 的文档测试示例

说了那么多,让我们先简单看个示例。如下是一段 Rust 中的注释代码:

# Examples
```rust
assert_eq!(2 + 2, 4);
```

Rust 在遍历了语法树之后,会:

e25d18b7d0d7dc0a7f870b8e29d0ca30.png

  1. 解析 markdown,寻找 Rust 语言的语法块(如果没有标注语言类型,默认是 Rust)

  2. 根据语法块,做一些简单的处理,生成可编译的代码

  3. 编译上述的测试代码 (如果编译失败,则说明测试失败)

  4. 运行这些测试 or 文档

如下是 Rustdoc 中将上述的代码生成测试代码的测试用例:

#![allow(unused)]
fn main() {
#[allow(non_snake_case)]
fn _doctest_main__some_unique_name() {
assert_eq!(2 + 2, 4);
}
_doctest_main__some_unique_name()
}

一旦上述的代码编译并运行通过,则说明文档中的注释是正确的。

详细见 Rustdoc 相关源码:librustdoc

构建文档体系:markdown 即 DSL

基于上述语言的文档体系,我们就能浮现出基本的原型。核心便是:基于 markdown 而扩展,将 markdown 视为可扩展的 DSL。如此以来,便可以按需添加功能,并根据不同需要进行可视化展示。

0. 基于 markdown

这一点倒是没有啥说的,markdown 在今天已经成为了事实上的开发文档标准。

1. 为扩展设计:文档 DSL

从做法上可以分为:

让语法块可运行。让 markdown 中的代码块包含更多的含义,根据不同的代码块来对语言进行特殊处理。如 Julia 的 Documenter.jl 便定义了一系列的如可执行的 eval 、REPL 环境输出的 repl、文档测试 jldoctest 等。除此,一旦我们使用特定的符号来标记时,我们就可以在代码中添加更多的可能性。

添加自定义符号。添加一些自定义的语法,以支持更多的高级功能。如 KotlinDoc/KDoc 中使用的 Dokka,使用 [] 来链接元素,这种方式和 markdown 比较贴进。

文档编排。通过自定义元素,实现在 markdown 对于内容的“编程”(管理、引用等)。如 Julia 的 Documenter.jl 中创建的 @ref、 @docs、 @meta、 @content 等语法。

而除了上述的内容,我们还可以做更多的事,诸如于对于“代码的引用”等。

2. 为准确性设计:文档测试

为了确保文档与代码保持一致,又或者是文档中代码的准确性,我们需要引入文档测试的方式来检查 API。以 Rust 和 Julia 这两个语言来分析的话,主要可以分为多种情况:

  • 代码编译通过。

  • 代码运行不报错。可以在其中支持语言本身的断言。

  • 与输出一致。文档需要输出程序的输出,它可以通过运行对应的测试,并保持两者是一致的。

主要的实现步骤可以参见上述的 Rust 语言实现。

3. 构建开放协作平台:开放协作

作为一个代码库的文档体系,它应该是开源的,能让所有的人为之做贡献,才会吸引到更多的开发者。

其它

人家苦短,让我们用 markdown 编程。

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值