php - 有效地描述 PHP 函数

Question

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

我需要告诉版主返回类型并列出每个函数的参数。我有数百个函数，所以这成为了一个问题，因为我需要对每个修订版都执行此操作。

我目前使用以下程序

1. ack-grep "函数">/tmp/functions2.在 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 studio 中显示:http://static.zend.com/topics/code-assist.png

特别是如果您正在使用这样的 IDE(除了 Zend 之外还有其他 IDE 可以这样做)，您可能会自然而然地记录每个函数和参数，因为它在您编写代码时会有所帮助。