通过“doc”解释源代码？

我为我的源代码使用PHPDoc和JSDoc。我知道有些工具可以从这些文档中构建API。但是，我想知道的是，如何解释复杂的代码？我只是在函数内使用多行注释而不是在PHPDoc/JSDoc中解释？通过“doc”解释源代码？

例如，考虑下面的代码：

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

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

是我的假设是否正确：

JSDoc/PHPDoc的仅写为那些谁是将要使用的函数/方法。
函数中的注释是为需要理解函数/方法背后的逻辑的人编写的。
文档独立于API和源代码注释，文档（每个软件都应该提供）是为那些想要使用该软件的人编写的。

但我不明白的是，在体系结构级别解释软件的原因 - 是否也有开发者文档？

你有什么策略来完善文档？

来源

2010-07-17 Tower

你的文档Public与那些工具的接口，你不希望API的消费者知道或关心实现的细节，你把这些注释放在代码本身。还有“完美”文档is not really a good goal。 BEST文档是以明显方式使用Interfaces的工作示例代码。在大多数情况下，单元测试很好地符合这个要求。

来源

2010-07-17 08:34:12

如何记录架构决策？ – Tower 2010-07-17 08:43:59

维基是最好的东西，因为它是一个实时文档，而这些决定通常是上下文和讨论/评论，因为有时候它们由于充分的理由而不够理想 – 2010-07-17 08:49:30

如果您确实需要记录有关函数内部工作的一些信息，主要只是代码的开发人员需要知道，phpDocumentor确实有@internal标记。

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

这听起来像是你想写的关于内部方法代码的描述将是这种内部使用的好候选。

来源

2010-07-19 17:11:33 ashnazg

通过“doc”解释源代码？

回答

相关问题