2020-10-27
使用工具生成和 API 符合的文档是现在大部分项目的选择，也可以说对于大部分开发者来说，使用生成的文档是时髦且优先的选择。即使对于很多语言来说，生成文档的方式更加繁琐，而且调整生成结果更是十分恼人。
那么生成的文档读起来有什么好处呢。我举一个 Flutter 的例子。Flutter 的文档分两种，一种包含可以互动的页面样例，用户可以直接更改网页上的代码看到输出结果。比如说这个页面的文档 https://api.flutter.dev/flutter/widgets/Form-class.html 。这种文档看起来十分优秀，易于阅读，很直观。细看的话你可以发现以上这篇文档也包含自动生成的 API 调用方式。实际上在 Flutter 大力修改文档之前，大部分的组件都是只包含自动生成的文档的。
我想，既然 Flutter 团队很喜欢也宣传自己使用类似 Java 的语法，这种非常类似 JavaDoc 的文档呈现方法大概就是从 Java 社区继承而来的吧。
JavaDoc 被广泛使用，甚至对于很多的包，在编写代码时 IDE 就会引导用户在 JavaDoc 中查看类的使用方法，而不是直接阅读源码实现或者反编译的内容。有一些 JavaDoc 包含从注释中提取的函数叙述，而更多的仅仅包含输入和输出的类型和变量名。
在只包含输入和输出的类型和变量名的 JavaDoc 中，相比源码阅读的优势恐怕尽在混淆之类的情况下更易阅读吧。即使包含从注释提取的叙述，也一眼可以从源码中阅读到一样的内容。
我们看 Dart 或者 TypeScript 这类在包发布时发布源码或者类型注释的纯文本的语言。需要类型提示的时候往往只需要直接查看源码，JavaDoc 类的文档没有什么帮助。
我认为好用的文档应该提供这些内容
总之，应该从用户的角度思考，如果我在使用这个库的时候，我需要的信息是什么。
对于想尝试这个解决方案的用户，我需要什么?
对于想找到一个使用方式的用户，我需要什么？
对于已经长时间使用的用户，我会遇到什么问题？
我正在 Brontosaurus 的文档是实践这样的思想，访问 https://brontosaurus.land 来看看吧！