通过“doc”解释源代码？

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

您使用这些工具记录公共接口，您不希望API的使用者知道或关心实现细节，您可以将这些注释放在代码本身中。也是“完美”的文档is not really a good goal。 BEST 文档正在使用以明显方式使用接口的示例代码。在大多数情况下，单元测试很好地满足了这个要求。

Answer 2

如果你真的觉得需要记录一些关于函数内部工作的东西，主要是只有代码的开发人员需要知道，phpDocumentor确实有@internal标记。

使用--parseprivate运行时选项时，非公共代码元素（如私有变量，受保护的方法等）在生成的文档中变得可见。通过@internal标记包含的文本也将变为可见。

在我看来，您想要编写的关于内部方法代码的描述对于@internal用法来说是个很好的选择。