通过“doc”解释源代码？ [关闭]答案

【问题标题】：Explaining source code via "doc"? [closed]通过“doc”解释源代码？ [关闭]
【发布时间】：2011-03-17 07:01:14
【问题描述】：

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

例如，考虑以下代码：

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

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

我的假设是否正确：

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

您有哪些完善文档的策略？

【问题讨论】：

【解决方案1】：

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

【讨论】：

【解决方案2】：

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

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

在我看来，您想要编写的有关内部方法代码的描述将是此类 @internal 用法的良好候选者。

【讨论】：