Эффективное описание функций PHP - PullRequest
Новая
       10

Эффективное описание функций PHP

3 голосов
/ 30 августа 2009

Как вы можете описать параметры и тип возврата (getter / setter) ваших функций PHP?

Мне нужно сообщить модератору тип возвращаемого значения и перечислить параметры для каждой функции. У меня есть сотни функций, так что это становится проблемой, так как мне нужно делать это для каждой ревизии.

Я сейчас использую следующую процедуру

  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 к каждому набору функций каждого файла

Ответы [ 2 ]

8 голосов
/ 30 августа 2009

Используйте что-то вроде 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, которые делают это), вы, вероятно, обнаружите, что естественным образом документируете каждую функцию и параметр, потому что это помогает вам, когда вы все равно кодируете.

4 голосов
/ 30 августа 2009

PHPDoc. Возьмем функцию суммы, которая добавляет два числа и возвращает результат в качестве примера: 

/**
 * Adds up two int numbers
 * @param int $x the first number to add
 * @param int $y the second number to add
 * @return int the result of the operation
 */
 function my_sum ($x, $y)
 {
     return $x+$y;
 }
...