Manuel Pear

Niveau superieur
Sommaire

Commentaires d'En-tête

Tous les fichiers de code source qui se trouvent dans le dépôt de PEAR doivent contenir le bloc de commentaires d'en-tête : Un bloc de commentaire << page-level >> en début de chaque fichier, et un bloc de commentaires << class-level >> juste au dessus de chaque classe.

  1. <?php
  2.  
  3. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */  
  4.  
  5. /**
  6. * Courte description du fichier
  7. *
  8. * Description plus détaillée du fichier (si besoin en est)...
  9. *
  10. * PHP versions 4 and 5
  11. *
  12. * LICENSE: This source file is subject to version 3.0 of the PHP license
  13. * that is available through the world-wide-web at the following URI:
  14. * http://www.php.net/license/3_0.txt. If you did not receive a copy of
  15. * the PHP License and are unable to obtain it through the web, please
  16. * send a note to license@php.net so we can mail you a copy immediately.
  17. *
  18. * @category NomCatégorie
  19. * @package   NomPaquetage
  20. * @author    Auteur original <auteur@example.com>
  21. * @author    Un autre author <autre@example.com>
  22. * @copyright 1997-2005 The PHP Group
  23. * @license   http://www.php.net/license/3_0.txt PHP License 3.0
  24. * @version   CVS: $Id:$
  25. * @link    http://pear.php.net/package/PackageName
  26. * @see      NetOther, Net_Sample::Net_Sample()
  27. * @since    File available since Release 1.2.0
  28. * @deprecated File deprecated in Release 2.0.0
  29. */  
  30.  
  31. /**
  32. * Placez ici les includes, les définitions de constantes
  33. * et les configurations des $_GLOBAL.
  34. * Assurez-vous d'ajouter les commentaires
  35. * docblocks pour éviter que phpDocumentor
  36. * assume qu'elles sont documentées dans les commentaires générals du fichier.
  37. */  
  38.  
  39. /**
  40. * Description courte de la classe
  41. *
  42. * Description plus détaillée de la classe (si besoin en est)...
  43. *
  44. * @category NomCatégorie
  45. * @package   NomPaquetage
  46. * @author    Auteur original <auteur@example.com>
  47. * @author    Un autre author <autre@example.com>
  48. * @copyright 1997-2005 The PHP Group
  49. * @license   http://www.php.net/license/3_0.txt PHP License 3.0
  50. * @version   Release: @package_version@
  51. * @link    http://pear.php.net/package/PackageName
  52. * @see      NetOther, Net_Sample::Net_Sample()
  53. * @since    Class available since Release 1.2.0
  54. * @deprecated Class deprecated in Release 2.0.0
  55. */  
  56. class Foo_Bar  
  57. {  
  58. }  
  59.  
  60.  
  61. ?> 

Balises requises ayant un contenu variable

Descriptions courtes

Les descriptions courtes doivent être fournies pour tous les commentaires docblocks. Elles doivent comporter des phrases courtes, non pas le nom de l'élément. Lisez le fichier d'exemple de la convention de codage pour avoir de bons exemples de descriptions.

Versions de PHP

Vous devez utiliser l'une des lignes suivantes dans les commentaires de la page:

.
 * PHP version 4
 * PHP version 5
 * PHP versions 4 and 5
@license

Il y a plusieurs licences possibles. Choisissez-en une dans ce qui suit et placez la dans les commentaires de la page et des classes :

.
 * @license http://www.apache.org/licenses/LICENSE-2.0  Apache License 2.0
 * @license http://www.freebsd.org/copyright/freebsd-license.html  BSD License (2 Clause)
 * @license http://www.debian.org/misc/bsd.license  BSD License (3 Clause)
 * @license http://www.freebsd.org/copyright/license.html  BSD License (4 Clause)
 * @license http://www.opensource.org/licenses/mit-license.html  MIT License
 * @license http://www.gnu.org/copyleft/lesser.html  LGPL License 2.1
 * @license http://www.php.net/license/3_0.txt  PHP License 3.0

Pour plus d'informations, consultez PEAR Group's Licensing Announcement.

@link

Ce qui suit doit être utilisé dans les commentaires de pages et de classes. Bien sûr, changez << NomPaquetage >> par le vrai nom de votre paquetage, cela permettra de générer un lien sur votre paquetage sur la documentation.

.
 * @link http://pear.php.net/package/NomPaquetage
@author

Il n'existe pas de vrai règle pour décider le moment où un contributeur de code doit être ajouté en tant qu'auteur. En général, leurs modifications doivent être "substentielles" (entre 10 et 20% de modifications). Des exceptions sont toutefois permises lors de la réécriture complète de fonctions ou la contribution de nouvelles approches.

La réorganisation de code ou les corrections de bogues ne justifient pas l'ajout d'une nouvelle personne en tant qu'auteur.

@since

Cette balise est requise lorsqu'un fichier ou une classe a été ajouté après la première release. N'utilisez pas cette balise pour une nouvelle release.

@deprecated

Cette balise est requise lorsqu'un fichier ou une classe n'est plus utilisé mais a été laissé en place pour assurer la compatibilité ascendante.

Balises optionnelles

@copyright

Utilisez les copyrights que vous voulez. Lorsque vous formattez cette balise, l'année doit comporter quatre chiffres. Si vous voulez couvrir une période avec le copyright, utilisez un tiret entre la première et la dernière année. Vous pouvez vous placer vous-mêmes en tant que détenteur du copyright, ou une list de personnes, ou une entreprise, ou le PHP Group, etc. Exemples :

.
 * @copyright 2003 John Doe and Jennifer Buck
 * @copyright 2001-2004 John Doe
 * @copyright 1997-2004 The PHP Group
 * @copyright 2001-2004 AFUP
Description de la licence

Si vous utilisez la licence PHP, utilisez la description fournie plus haut. Si une autre licence est utilisée, merci de supprimer la description de la licence PHP. Vous pouvez y placer votre propre description en prenant soin de préfixer le texte par LICENSE: pour faciliter sa localisation.

@see

Ajoutez une balise @see quand vous voulez envoyer les utilisateurs vers d'autres sections de la documentation du paquetage. Si vous avez plusieurs éléments, séparez les avec des virgules plutôt que d'ajouter d'autre balises @see.

Ordre et espacement

Pour faciliter la lisibilité à long terme de vos codes sources PEAR, les textes et les balises doivent se conformer à l'ordre et aux emplacements utilisés dans l'exemple précédent. Ce standard a été adopté à partit du standard JavaDoc.

Utilisation de @package_version@

Il y'a deux façon de mettre en place les remplacements de @package_version@. La procédure dépend de si vous écrivez à la main le fichier package.xml ou si vous utilisez PackageFileManager.

Les personnes écrivant le fichier package.xml à la main doivent ajouter un élément <replace> pour chaque fichier. Le XML devrait ressembler à cela:

<file name="Class.php">
  <replace from="@package_version@" to="version" type="package-info" />
</file>

Les mainteneurs utilisant le paquetage PackageFileManager doivent appeler addReplacement() pour chaque fichier:

  1. <?php
  2. $pkg->addReplacement('filename.php', 'package-info', 
  3.                '@package_version@', 'version'  
  4. ?> 

Règles de transition

Petits paquetages

Les paquetages qui existent déjà et comportent un petit nombre de fichiers doivent adopter les commentaires docblocks avant la prochaine release.

Paquetages volumineux

Les paquetages qui existent déjà et comportent un grand nombre de fichiers sont encouragés à adopter la nouvelle convention le plus tôt possible. La modification sera obligatoire lors de la publication d'une nouvelle mise à jour majeure du paquetage.

Paquetages nouveaux ou non-releasés

Les nouveaux paquetages ou les paquetages ne comptabilisant aucune release doivent inclure les commentaires docblocks avant d'être publiés.

Niveau superieur
Sommaire

Remonter Remonter
L'éditeur javascript - CSS - Gentoo - Tutoriaux PHP - Tutoriels PHP - Bretagne - php - Moto - Kit graphique