2

我正在为我的源代码使用 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 和源代码注释是分开的，文档（每个软件都应该提供）是为那些想要使用该软件的人编写的。

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

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

4

2 回答 2

2

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

于 2010-07-17T08:34:12.860 回答
1

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

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

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

于 2010-07-19T17:11:33.890 回答