文档样式[关闭]

我是一个PHP Web开发人员,他正在寻找一种行之有效的方法来编写一个好的文档(又名docblock)。

有几种文档样式,例如:

• 描述性但未分类(1):

/**
 *  Element name: class, function, variable etc. (Optional)
 *  
 *  Short description.
 *
 *  Long description.
 */

• 分类(2):

/**
 *  Function name
 *
 *  @param $foo
 *  @return bar
 */

• 类似(3)的模板:

/**
 **********************
 * NAME:    Func_Name
 * DESC:    Does A Lot
 * RETurn:  number
 * NOTES: foo bar foo...
 **********************
 */

• 上述方法的变更。

但我应该采用哪种文档样式?

我假设不同的文档样式应该用于不同的语言元素:
函数可能应该使用2方法,
而类应该使用1方法。

内联代码可以这样记录(5):

// short description
// of
// what the following code does.

我知道phpdocumentor,但不喜欢学习如何使用它。
学习如何使用phpdocumentor之类的东西,以便记录我的代码,这似乎很荒谬。
(尽管我很欣赏任何开源项目,包括phpdocumentor)