有效地描述PHP函数

Question

如何描述PHP函数的参数和返回类型(getter/setter)？

我需要告诉我的主持人返回类型并列出每个函数的参数.我有数百个函数,所以这成为问题,因为我需要为每个修订版本执行此操作.

我现在使用以下程序

1. ack-grep "function " > /tmp/functions 2.在Vim:
   • %s/\d//g, %s/{//, %s/://g
   • `%S /.*.PHP /\U&/
   • 然后将大写文件名放在每个文件的函数列表的开头
   • 将函数放到一个文件中,将参数放到另一个文件中,以便亚麻布匹配
   • 创建第三个文件,在其中写入setter或写入getter相应的行
2. paste -d"&" /tmp/{functions,functions_param,functions_type}
3. 将LaTeX格式添加到每个文件的每组功能

Answer 1

使用像phpdoc这样的东西.

基本上你会在代码中添加特殊注释:

/**
 * A sample function docblock
 * @global string document the fact that this function uses $_myvar
 * @staticvar integer $staticvar this is actually what is returned
 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer 
 */
function firstFunc($param1, $param2 = 'optional') {
    static $staticvar = 7;
    global $_myvar;

    return $staticvar;
}

它会自动为它生成HTML文档.

基本上,这背后的想法是让程序员的生活更轻松,并允许编写内联API文档而无需花费大量时间.

有些IDE也能理解这一点,并会在您使用它时显示文档.例如,功能:

/** Retrieve the action key
 * @return string
 */
function isValid($value) {
  ....
}

在Zend工作室中显示:http://static.zend.com/topics/code-assist.png

特别是如果你正在使用这样的IDE(除了Zend之外还有其他人这样做),你可能会发现自然会记录每个函数和参数,因为它可以帮助你进行编码.