这两个概念似乎违反直觉。论证的一方是看到评论对可读性造成的伤害，以及违反DRY的情况（如果评论甚至保持最新）。但是，翻转硬币并有必要为您的代码提供良好的API文档，以便其他人可以使用您的库。
我见过的每个工具（JSDoc，PDoc等）都是为生成API文档而设计的，它使用了极大的空间来提供文档。我需要提供API文档，我不需要的是让我的一半LOC被特别格式化的注释，以便JSDoc可以读取它。
我正在考虑使用基本的降价工具，例如Jekyll，并将此文档放在/ doc文件夹中，将其从我的代码中完全删除。还有其他人找到了解决这个问题的方法吗？
答案 0 :(得分：0)
Sphinx是一种适用于多种语言的文档工具，它假设您将文档主要编写在外部文件中。它仍有autodoc扩展名，允许您从代码中的注释中提取文档。
我个人觉得将API文档放在代码附近会更方便，因为它可以帮助我保持最新。此外，处理该代码的其他人将能够在他们需要时获得文档，而无需浏览外部文件。我坦率地说，大多数代码都是注释没有任何错误：编辑通常会对注释进行不同的着色，并允许您根据需要忽略它们。