Quel est le bon format de documentation de la fonction PHP?

Question

Documentation de PHP est un animal sauvage, même les underscore_vsCamelCase style n'est-ce pas varié. Donc, compte tenu de tous les types de documentation de PHP que j'ai vu jusqu'à présent - ce qui est la norme? Comment sont mes fonctions et méthodes censé être marqué vers le haut de sorte que la majorité des IDE et de la documentation, les bibliothèques peuvent les lire?

Dans les exemples ci-dessous (type) est l'un des:

• bool
• int
• tableau
• objet
• chaîne
• flotteur

et le nom est juste le nom de la variable de param ($valeurs)

/*
 * Function name
 *
 * what the function does
 *
 * @param (type) about this param
 * @return (type)
 */
function example((name))

/*
 * What the function does
 *
 * @param (name) about this param
 * @return (name)
 */
function example((name))

/**
 * Function name
 *
 * what the function does
 *
 * @param (type) (name) about this param
 * @return (type) (name)
 */
function example((name))

/**
 * Function name
 * what the function does
 *
 * Parameters:
 *     (name) - about this param
 */
function example((name))

Answer 1

Il n'est pas officiel, selon Hoyle, style de commentaires. Le plus proche que vous trouverez est le Zend Framework directives de codage. Zend Framework est produite par Zend, qui est profondément impliqué dans la création de PHP, donc on pourrait dire que leurs règles de codage sont ceux qui doivent être suivies.

Il pourrait aussi faire valoir que tout commentaire qui prend la forme

/** <--- starts with
*/  <--- ends with

Est un "officiel" de la documentation au format, elles seront analysées et mises à disposition via l'API reflection. Beaucoup de gens de tirer profit de cette, et la PHPDoc format pour produire un fonctionnaire-ish format de commentaire.

Answer 2

Beaucoup de gens utilisent PHPdoc comme standard.

Answer 3

Je pense que PHPDoc est à peu près standard. De plus, votre question a déjà été posée (ce qui vous donne peut-être quelques idées supplémentaires).

Answer 4

Cela vaut peut-être la peine de jeter un coup d’œil à doxygen . Il dispose d'un support multilingue et d'un format d'entrée standard.