在代碼文檔中標記「示例用法」

Question

在代碼文檔中放置示例用法的最佳做法是什麼？有沒有標準化的方法？用@usage或@notes？文檔生成器是否傾向於支持這一點？

我知道這個問題應該取決於文檔生成器。然而，我試圖習慣於在進入每個生成器的特質之前使用評論風格來生成文檔;似乎有更多的相似之處。

我已經嘗試過使用Doxygen &經常使用AS3，JS，PHP，Obj-C，C++。

例如：

/** 
* My Function 
* @param object id anObject 
* @usage a code example here... 
*/ 
function foo(id) { 

} 

或

/** 
* My Function 
* @param object id anObject 
* @notes a code example here, maybe? 
*/ 
function foo(id) { 

} 

由於

Answer 1

Doxygen的具有命令@example，並且有很多的用於配置例如源極路徑的選項。

我認爲Doxygen和其他文檔工具之間有一套常見的命令，但它們對於良好的文檔編制來說太少了。您需要特別指出從特定工具中獲得最佳效果。 我喜歡Doxygen，因爲它是開源並且高度可配置的。但這只是我的看法。

也許你可以配置doxygen與@xrefitem別名以允許解析與其他文檔工具定義的文檔註釋。