documentation - 通过 "doc"解释源代码？

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改进这个问题？更新问题，以便 editing this post 可以用事实和引用来回答它.

4年前关闭。




Improve this question




我正在为我的源代码使用 PHPDoc 和 JSDoc。我知道有一些工具可以从这些文档中构建 API。但是，我想知道的是，应该如何解释复杂的代码？我是否只是在函数中使用多行注释而不是在 PHPDoc/JSDoc 中进行解释？

例如，考虑以下代码:

/**
 * Lorem ipsum dolor sit amet.
 * @param {Integer} width
 * @return {Boolean}
 */
function setWidth(width) {
 // Very complex code goes here...
}

在上述情况下，我应该如何去注释复杂的代码？我认为我不能在 JSDoc 中做到这一点，因为它用于构建 API(这是关于“如何使用”而不是“事情如何工作”)，对吧？

我的假设是否正确:

JSDoc/PHPDoc 是专门为那些将要使用函数/方法的人编写的。

函数中的注释是为需要了解函数/方法背后逻辑的任何人编写的。

文档与 API 和源代码注释是分开的，文档(每个软件都应该提供)是为那些想要使用该软件的人编写的。

但我不明白的是，在架构级别解释软件的内容——是否也应该有开发人员文档？

您完善文档的策略是什么？

Answer 1

您的文件 公众号 与这些工具的接口(interface)，您不希望 API 的使用者知道或关心实现细节，您将这些注释放在代码本身中。还有“完美”的文档 is not really a good goal . 最佳 文档是以明显的方式使用接口(interface)的工作示例代码。在大多数情况下，单元测试很好地满足了这个要求。