Documentation 通过“解释源代码”；博士；？

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

但我不明白的是，是什么在体系结构层面上解释了软件——是否也应该有开发人员文档

---

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

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

如果您确实觉得有必要记录函数的内部工作原理，这主要是代码开发人员需要知道的，那么phpDocumentor确实有@internal标记

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

---

在我看来，你想写的关于内部方法代码的描述很适合这种@internal用法。

如何记录架构决策？Wiki是最好的，因为它是一个实时文档，而这些决定通常是根据上下文和讨论/评论做出的，因为有时出于充分的理由，它们不是最优的