dimanche 21 avril 2013

php documentor, marqueurs utiles...


La documentation du code, c'est tout simplement INDISPENSABLE !!!

Nous utilisons phpDocumentor qui s'installe simplement avec PEAR:
$ pear channel-discover pear.phpdoc.org
$ pear install phpdoc/phpDocumentor-alpha

Et qui vous permet de générer la documentation correspondant à votre répertoire courant vers le répertoire "documentation" a l'aide de la ligne suivante:
$ phpdoc -d . -t documentation
L'ensemble de la documentation sur la prise en charge des commentaires est disponible ici, et voici la liste des marqueurs les plus utiles:
  • @api : utilisé pour signaler que l'élément stucturel est exploité par des services tiers
  • @author: l'auteur de l'élément.
    Syntaxe: @author [name] [<email address>]
  • @category : catégorie pour l'organisation de groupes de packages
    Syntaxe: @category [description]
  • @copyright : informations sur le copyright
    Syntaxe: @copyright [description]
  •  @deprecated : signale que l'élément est déprécié.
    Syntaxe:  @deprecated [<version>] [<description>]
  •  @example : affiche le code d'un fichier spécifié
    Syntaxe:
    @example [location] [<start-line> [<number-of-lines>] ] [<description>]
  •  @filesource : indique à phpDocumentor d'inclur la source du fichier dans le résultat
  • @ignore : pour ignorer l'élément dans la documentation
    Syntaxe:
    @ignore [<description>
  • @internal: indique que l'élément est interne à l'application ou la librairie
    Syntaxe:
    @internal [description]
  •  @license : indique la licence applicable
    Syntaxe: @license [<url>] [name]
  •  @link: définition d'une relation entre l'élément et le site web, identifié par l'url absolue
    Syntaxe:
    @link [URI] [<description>]
  •  @method : indique les méthodes "magique" qui peuvent être appelées
    Syntaxe:
    @method [return type] [name]([[type] [parameter]<, ...>]) [<description>]
  •  @package : permet de structurer l'élément en sous catégories logiques
    Syntaxe:
    @package [level 1]\[level 2]\[etc.]
  • @param : définition d'un argument d'une méthode ou fonction
    Syntaxe:
    @param [Type] [name] [<description>]
  • @property : indique les propriés "magiques" présentes ( __get(), __set())
    Syntaxe:
    @property [Type] [name] [<description>]      
  • @property-read : indique les propriés "magiques" présentes en lecture seule
    Syntaxe:
    @property-read [Type] [name] [<description>] 
  • @property-write : indique les propriés "magiques" présentes en ecriture seule
    Syntaxe:
    @property-read [Type] [name] [<description>]
  • @return :  documente le renvoi d'une fonction ou méthode
    Syntaxe: @return [Type][<description>]
  • @see: indique une référence à un site internet ou un autre élément structurel
    Syntaxe: @see [URI | Type | FQSEN] [<description>]
  • @throws : indique quand l'élément structurel gére un type d'exception donné
    Syntaxe: @throws [Type] [<description>]
  • @version: indique la version courante de l'élément
    Syntaxe: @version [<vector>] [<description>]

 Les "éléments structurel" sont les partie du code qui devraient avoir leur bloc de commentaires (espace de nom, require(_once), include(_once), classes, interface, traitement, fonctions (et méthodes), propriétés, constantes)

Aucun commentaire: