Flutter 应用程序文档应该是什么样的？

Question

我必须评论/提供我用 flutter 创建的应用程序的文档。

我已经看到DartDoc生成文档。但这仅适用于我的应用程序中的 Dart 代码，这基本上意味着业务逻辑。用户界面怎么样？评论 UI 或将其包含在文档中的最佳方式是什么？

另外，一个有据可查的应用程序是否应该只有“dartdoc 评论” ///？//与 dartcode 注释相比，基本注释的作用是什么？是的，它不会出现在文档中，但我应该如何选择？

Answer 1

Flutter 代码与 Dart 代码没有什么不同，只是它引用了 Flutter 库。因此，您是否想使用 DartDoc，取决于您。

所以一般的经验法则是：

• 使用 DartDoc 注释来记录您可以从其他代码访问的代码（例如成员和类型，如您链接的有效 Dart 指南所建议的），特别是因为它们允许您使用 Markdown 格式详细了解（通过添加丰富的内容）由 DartDoc 提供。

• 使用常规注释来记录代码的工作原理，例如在方法内部。

一个好的库 应该记录其公开的成员/类型，以便其他开发人员可以快速掌握其功能。

总而言之，两者并不排斥，无论您只使用 Dart 还是 Dart+Flutter，您都可以使用常规注释和/或 DartDoc 注释来记录您的代码。