PHPDoc : Différence entre versions

De OviWiki
Aller à : navigation, rechercher
(→‎Syntaxes)
(→‎Syntaxes)
Ligne 41 : Ligne 41 :
 
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 @ :
  
−
'''@author Société Cantico'''
+
{| class="wikitable"
 +
|+ Common tags
 +
! Tag
 +
! Usage
 +
! Description
 +
|-
 +
|@abstract
 +
|
 +
|Documents an abstract class, class variable or method.
 +
|-
 +
|@access
 +
|public, private or protected
 +
|Documents access control for an element.  @access private indicates that documentation of element be prevented.
 +
|-
 +
|@author
 +
|author name <author@email>
 +
|Documents the author of the current element.
 +
|-
 +
|@copyright
 +
|name date
 +
|Documents copyright information.
 +
|-
 +
|@deprecated
 +
|version
 +
|Documents a method as deprecated.
 +
|-
 +
|@deprec
 +
|
 +
|same as @deprecated
 +
|-
 +
|@example
 +
|/path/to/example
 +
|Documents the location of an external saved example file.
 +
|-
 +
|@exception
 +
|
 +
|documents an exception thrown by a method &mdash; also see @throws.
 +
|-
 +
|@global
 +
|type $globalvarname
 +
|Documents a global variable or its use in a function or method.
 +
|-
 +
|@ignore
 +
|
 +
|Prevents the documentation of an element
 +
|-
 +
|@internal
 +
|
 +
|private information for advanced developers
 +
|-
 +
|@link
 +
|URL
 +
|
 +
|-
 +
|@name
 +
|global variable name
 +
|Specifies an alias for a variable.  For example, $GLOBALS['myvariable'] becomes $myvariable
 +
|-
 +
|@magic
 +
|
 +
|
 +
|-
 +
|@package
 +
|name of a package
 +
|Documents a group of related classes and functions.
 +
|-
 +
|@param
 +
|type [$varname] description
 +
|
 +
|-
 +
|@return
 +
|type description
 +
|This tag should not be used for constructors or methods defined with a ''void'' return type.
 +
|-
 +
|@see
 +
|
 +
|Documents an association to another method or class.
 +
|-
 +
|@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
 +
|
 +
|
 +
|-
 +
|@throws
 +
|
 +
|Documents an exception thrown by a method.
 +
|-
 +
|@todo
 +
|
 +
|Documents things that need to be done to the code at a later date.
 +
|-
 +
|@var
 +
|type
 +
|a data type for a class variable
 +
|-
 +
|@version
 +
|
 +
|Provides the version number of a class or method.
 +
|}
  
−
Auteur de l'objet
 
  
−
'''@version 3.2.6'''
+
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 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].
+

Version du 26 mai 2009 à 14:07

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 : <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 @ :

Common tags
Tag Usage Description
@abstract Documents an abstract class, class variable or method.
@access public, private or protected Documents access control for an element. @access private indicates that documentation of element be prevented.
@author author name <author@email> Documents the author of the current element.
@copyright name date Documents copyright information.
@deprecated version Documents a method as deprecated.
@deprec same as @deprecated
@example /path/to/example Documents the location of an external saved example file.
@exception documents an exception thrown by a method — also see @throws.
@global type $globalvarname Documents a global variable or its use in a function or method.
@ignore Prevents the documentation of an element
@internal private information for advanced developers
@link URL
@name global variable name Specifies an alias for a variable. For example, $GLOBALS['myvariable'] becomes $myvariable
@magic
@package name of a package Documents a group of related classes and functions.
@param type [$varname] description
@return type description This tag should not be used for constructors or methods defined with a void return type.
@see Documents an association to another method or class.
@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
@throws Documents an exception thrown by a method.
@todo Documents things that need to be done to the code at a later date.
@var type a data type for a class variable
@version Provides the version number of a class or method.


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=4359 »