原文地址：felixblaschke.medium.com/let-me-help…
原文作者：felixblaschke.medium.com/
发布时间：2021年10月14日
两年多来，我一直在创建Flutter和Dart包。在这段时间里，我学到了一件重要的事情。
提供一个很棒的自述文件是关键，以使开发人员能够利用你的技术作品。
我花了很多时间为我的包提供最好的文档。但我制作的内容越多，自述文件就越混乱。同时，我的代码例子也随着时间的推移而被淘汰。
为了解决这个问题，我写了一个Dart脚本，它可以
- 自动嵌入外部Dart文件中的代码例子，这样IDE就能检查出语法错误
- 根据所用的markdown标题创建 "目录"，以创建大而清晰的readme文件
- 使用markdown包含，将readme结构化为多个文件。
这个月我把这个脚本改写成了Dart应用程序的readme_helper，所以每个Flutter和Dart的开发者都可以在自己的项目中使用这些功能。
readme_helper是一个markdown代码生成器，可以在你的markdown文件中寻找特殊类型的HTML注释。
<！-- #code path/to/file.dart -->
代码生成器将用包含的代码替换注释。如果外部文件发生变化，它将更新它。 对于范围内的代码嵌入，你可以放置标记注释。
import 'dart:math';
// #begin
class MyClass {
// #skip
int someMethod() {
return Random().nextInt(1);
}
// #resume
String interestingMethod() {
return 'Foo';
}
}
// #end
这将创建以下内容。
class MyClass {
...
String interestingMethod() {
return 'Foo';
}
}
而每当我的例子的API出现故障时，我的IDE中的Dart分析器就会提示我的file.dart中的错误。 你可以用以下方法安装readme_helper
flutter pub global activate readme_helper
来安装readme_helper，并通过以下方式运行readme_helper
flutter pub global run readme_helper 。
更多信息请阅读软件包readme，了解所有功能。
我希望你喜欢它。
直到下一次
- 菲利克斯-
