PHPDoc : Différence entre versions

De OviWiki
Aller à : navigation, rechercher
(→‎Syntaxes)
 
(6 révisions intermédiaires par 2 utilisateurs non affichées)
Ligne 7 : Ligne 7 :
 
Commentaire sur une propriété de classe :
 
Commentaire sur une propriété de classe :
 
<source lang="php">
 
<source lang="php">
−
    /**
+
 
−
    * Message de bienvenue
+
/**
−
    *
+
* Message de bienvenue
−
    * @var    string message de bienvenue
+
*
−
    * @access private
+
* @var    string message de bienvenue
−
    */
+
* @access private
−
    var $message;
+
*/
 +
var $message;
 +
 
 
</source>
 
</source>
  
 
Commentaire sur une méthode de classe :
 
Commentaire sur une méthode de classe :
 
<source lang="php">
 
<source lang="php">
−
    /**
+
/**
−
    * Créé le message
+
* Créé le message
−
    * et le stocke dans $this->message
+
* et le stocke dans $this->message
−
    *
+
*
−
    * @access  public
+
* @access  public
−
    * @return  none
+
* @return  none
−
    */
+
*/
−
    function creationMessage() {
+
function creationMessage() {
 
        
 
        
−
    }
+
}
 
</source>
 
</source>
  
 
==Syntaxes==
 
==Syntaxes==
  
−
On utilise la balise de commentaires pour lignes multiples :
+
On utilise la balise de commentaires pour lignes multiples (les 2 étoiles en première ligne sont nécessaires à l'interprétation des commentaires comme étant du PHPDoc) :
 
<source lang="php">
 
<source lang="php">
−
/* */
+
/**
 +
*
 +
*
 +
*/
 
</source>
 
</source>
  
Ligne 41 : Ligne 46 :
 
Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, on utilise des tags préfixés par le caractère arobas @ :
 
Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, on utilise des tags préfixés par le caractère arobas @ :
  
−
{| class="wikitable"
+
{| class="prettytable sortable"
−
|+ Common tags
+
|+ Tags PHPDoc
 
! Tag
 
! Tag
−
! Usage
+
! Valeurs
 
! Description
 
! Description
 
|-
 
|-
 
|@abstract
 
|@abstract
 
|
 
|
−
|Documents an abstract class, class variable or method.
+
|L'objet est abstrait.
 
|-
 
|-
 
|@access
 
|@access
 
|public, private or protected
 
|public, private or protected
−
|Documents access control for an element.  @access private indicates that documentation of element be prevented.
+
|Accessibilité de l'objet.
 
|-
 
|-
 
|@author
 
|@author
−
|author name <author@email>
+
|Nom de l'auteur de l'objet <emaildelauteur@email.com>
−
|Documents the author of the current element.
+
|Nom et adresse e-mail de l'auteur
 
|-
 
|-
 
|@copyright
 
|@copyright
−
|name date
+
|nom date
−
|Documents copyright information.
+
|Copyright.
 
|-
 
|-
 
|@deprecated
 
|@deprecated
 
|version  
 
|version  
−
|Documents a method as deprecated.
+
|Indique que l'objet est obsolète.
−
|-
+
−
|@deprec
+
−
|
+
−
|same as @deprecated
+
−
|-
+
−
|@example
+
−
|/path/to/example
+
−
|Documents the location of an external saved example file.
+
 
|-
 
|-
 
|@exception
 
|@exception
 
|
 
|
−
|documents an exception thrown by a method &mdash; also see @throws.
+
|Exception lancée par une méthode (voir aussi @throws).
 
|-
 
|-
 
|@global
 
|@global
−
|type $globalvarname
+
|type(string, int, boolean, array, object NomObjet...) $globalvarname
−
|Documents a global variable or its use in a function or method.
+
|Variable globale.
−
|-
+
−
|@ignore
+
−
|
+
−
|Prevents the documentation of an element
+
−
|-
+
−
|@internal
+
−
|
+
−
|private information for advanced developers
+
 
|-
 
|-
 
|@link
 
|@link
 
|URL
 
|URL
−
|
+
|URL associée à l'objet (redirection vers une documentation)
−
|-
+
−
|@name
+
−
|global variable name
+
−
|Specifies an alias for a variable.  For example, $GLOBALS['myvariable'] becomes $myvariable
+
−
|-
+
−
|@magic
+
−
|
+
−
|
+
 
|-
 
|-
 
|@package
 
|@package
−
|name of a package
+
|nom du package
−
|Documents a group of related classes and functions.
+
|Nom du package de l'objet.
 
|-
 
|-
 
|@param
 
|@param
−
|type [$varname] description
+
|type(string, int, boolean, array, object NomObjet...) [$varname] description
−
|
+
|Décrit un paramètre à une fonction
 
|-
 
|-
 
|@return
 
|@return
−
|type description
+
|type(string, int, boolean, array, object NomObjet...) description
−
|This tag should not be used for constructors or methods defined with a ''void'' return type.
+
|Définit la valeur de retour d'une fonction.
 
|-
 
|-
−
|@see
+
|@static
 
|
 
|
−
|Documents an association to another method or class.
+
|Indique que l'objet est statique
 
|-
 
|-
 
|@since
 
|@since
−
|version
 
−
|Documents when a method was added to a class.
 
−
|-
 
−
|@static
 
−
|
 
−
|Documents a static class or method
 
−
|-
 
−
|@staticvar
 
−
|
 
−
|Documents a static variable's use in a function or class
 
−
|-
 
−
|@subpackage
 
−
|
 
 
|
 
|
 +
|Permet d'indiquer un numéro de version du produit à partir de laquelle l'objet sera utilisable
 
|-
 
|-
 
|@throws
 
|@throws
 
|
 
|
−
|Documents an exception thrown by a method.
+
|Exception lancée par une méthode (voir aussi @throws).
 
|-
 
|-
 
|@todo
 
|@todo
 
|
 
|
−
|Documents things that need to be done to the code at a later date.
+
|Permet d'indiquer une description d'une tâche à accomplir prochainement sur l'objet.
 
|-
 
|-
 
|@var
 
|@var
−
|type
+
|type(string, int, boolean, array, object NomObjet)
−
|a data type for a class variable
+
|Type de la propriété
 
|-
 
|-
 
|@version
 
|@version
 
|
 
|
−
|Provides the version number of a class or method.
+
|Version de l'objet.
 
|}
 
|}
  
  
 
Pour plus d'informations sur les tags, vous pouvez voir ces sites : [http://en.wikipedia.org/wiki/PHPDoc Wikipedia PHPDoc], [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html PHPDocumentor manuel]...
 
Pour plus d'informations sur les tags, vous pouvez voir ces sites : [http://en.wikipedia.org/wiki/PHPDoc Wikipedia PHPDoc], [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html PHPDocumentor manuel]...

Version actuelle en date du 25 juin 2009 à 08:32

Commenter un code est la meilleure aide que vous pouvez donner aux développeurs qui réutiliseront votre code.

Pour cela, nous conseillons d'utiliser la syntaxe de PHPDoc pour vos commentaires. PHPDoc est une adaptation de JavaDoc au langage PHP. Un commentaire écrit en PHPDoc sera facilement compréhensible par un développeur ainsi que par des logiciels générateurs de documentations (PHPDocumentor, Doxygen, PHPDoc, AutoPHPDoc...). Des éditeurs de codes savent interpréter le PHPDoc pour faire de l'auto-suggestion (ex : Eclipse).

Exemples de commentaires

Commentaire sur une propriété de classe : <source lang="php">

/** 

* Message de bienvenue
*
* @var    string message de bienvenue
* @access private
*/

var $message;

</source>

Commentaire sur une méthode de classe : <source lang="php"> /** 

* Créé le message
* et le stocke dans $this->message
*
* @access  public
* @return  none
*/

function creationMessage() {

} </source>

Syntaxes

On utilise la balise de commentaires pour lignes multiples (les 2 étoiles en première ligne sont nécessaires à l'interprétation des commentaires comme étant du PHPDoc) : <source lang="php"> /** 

* 
* 
*/

</source>

Le premier paragraphe est dédié à la description courte de l'objet commenté, le deuxième à la description longue.

Pour préciser la version d'une fonction, l'auteur d'une classe ou encore le type de l'objet, on utilise des tags préfixés par le caractère arobas @ :

Tags PHPDoc
Tag Valeurs Description
@abstract L'objet est abstrait.
@access public, private or protected Accessibilité de l'objet.
@author Nom de l'auteur de l'objet <emaildelauteur@email.com> Nom et adresse e-mail de l'auteur
@copyright nom date Copyright.
@deprecated version Indique que l'objet est obsolète.
@exception Exception lancée par une méthode (voir aussi @throws).
@global type(string, int, boolean, array, object NomObjet...) $globalvarname Variable globale.
@link URL URL associée à l'objet (redirection vers une documentation)
@package nom du package Nom du package de l'objet.
@param type(string, int, boolean, array, object NomObjet...) [$varname] description Décrit un paramètre à une fonction
@return type(string, int, boolean, array, object NomObjet...) description Définit la valeur de retour d'une fonction.
@static Indique que l'objet est statique
@since Permet d'indiquer un numéro de version du produit à partir de laquelle l'objet sera utilisable
@throws Exception lancée par une méthode (voir aussi @throws).
@todo Permet d'indiquer une description d'une tâche à accomplir prochainement sur l'objet.
@var type(string, int, boolean, array, object NomObjet) Type de la propriété
@version Version de l'objet.


Pour plus d'informations sur les tags, vous pouvez voir ces sites : Wikipedia PHPDoc, PHPDocumentor manuel...

Récupérée de « https://wiki.ovidentia.fr/index.php?title=PHPDoc&oldid=4549 »