我正在使用 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 和源代码注释分开，文档(每个软件都应该提供)是为那些想要使用该软件的人编写的。
但我不明白的是，在架构级别上解释软件的是什么 - 是否也应该有开发人员文档？
您完善文档的策略是什么？
最佳答案
您使用这些工具记录公共(public)接口(interface)，您不希望 API 的使用者了解或关心实现细节，您可以将这些注释放在代码本身中。也是“完美”的文档is not really a good goal 。 BEST 文档是以明显方式使用接口(interface)的工作示例代码。在大多数情况下，单元测试很好地满足了这一要求。
关于documentation - 通过 "doc"解释源代码？，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/3270758/