通過「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」解釋源代碼？

回答

相關問題