2

这两个概念似乎违反直觉。争论的一方面认为评论对可读性造成的伤害，以及违反 DRY（如果评论甚至保持最新）。但是，掷硬币，有必要为您的代码提供良好的 API 文档，以便其他人可以使用您的库。

我见过的每一个为生成 API 文档而设计的工具（JSDoc、PDoc 等）都使用大量的空间来提供该文档。我需要提供 API 文档，我不需要将我的一半 LOC 设置为特殊格式的注释，以便 JSDoc 可以读取它。

我目前正在考虑使用像Jekyll这样的基本降价工具，并将此文档放在 /doc 文件夹中，从我的代码中完全删除它。有没有其他人找到对他们有用的解决这个问题的方法？

4

1 回答 1

0

Sphinx是一种适用于多种语言的文档工具，它假定您将主要在外部文件中编写文档。它仍然有一个autodoc扩展，允许您从代码中的注释中提取文档。

我个人觉得将 API 文档放在代码附近会更方便，因为它可以帮助我保持最新。此外，处理该代码的其他人将能够在需要时获得文档，而无需浏览外部文件。坦率地说，我认为大多数代码行都是注释没有任何问题：编辑器通常会为注释着色，并允许您根据需要忽略它们。

于 2011-03-17T18:06:33.373 回答