Description efficace des fonctions PHP

Question

Comment pouvez-vous décrire les paramètres et le type de retour (getter/setter) de vos fonctions PHP?

J'ai besoin de dire à mon modérateur le type de retour et de lister les paramètres pour chaque fonction. J'ai des centaines de fonctions donc cela devient un problème, car je dois le faire pour chaque révision.

J'utilise au moment où la procédure suivante

1. ack-grep "function " > /tmp/functions 2. dans vim:
   • %s/\d//g, %s/{//, %s/://g
   • `% s /.* php/\ U &/
   • mettre ensuite le nom du fichier Majuscule au début de la liste des fonctions de chaque fichier
   • fonctions posées. un fichier et les paramètres à un autre fichier de telle sorte que les linenumbers correspondent
   • créer un troisième fichier où vous écrivez soit setter ou getter pour la ligne correspondante
2. paste -d"&" /tmp/{functions,functions_param,functions_type}
3. ajouter la mise en forme LaTeX à chaque ensemble de fonctions de chaque fichier

Answer 1

Utilisez quelque chose comme phpdoc.

Fondamentalement, vous ajoutez des commentaires spéciaux à votre code:

/** 
* 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; 
} 

et il génère automatiquement la documentation HTML pour elle. Fondamentalement, l'idée sous-jacente est de faciliter la vie d'un programmeur et de permettre l'écriture de documentation API en ligne sans avoir à y consacrer beaucoup de temps.

Certains IDE comprennent cela et affichent la documentation pendant que vous l'utilisez. Par exemple, la fonction:

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

Affiche ce en studio Zend: http://static.zend.com/topics/code-assist.png

Surtout si vous utilisez un IDE comme celui-ci (il y a d'autres encore Zend qui le font), vous trouverez probablement vous documentez naturellement chaque fonction et chaque paramètre, car cela vous aide pendant que vous codifiez de toute façon.

Answer 2

phpdoc. Prenant la fonction somme qui ajoute deux nombres et renvoie le résultat comme un exemple:

/** 
* 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; 
}