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.
<?php
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
/**
* Courte description du fichier
*
* Description plus détaillée du fichier (si besoin en est)...
*
* PHP versions 4 and 5
*
* LICENSE: This source file is subject to version 3.0 of the PHP license
* that is available through the world-wide-web at the following URI:
* http://www.php.net/license/3_0.txt. If you did not receive a copy of
* the PHP License and are unable to obtain it through the web, please
* send a note to license@php.net so we can mail you a copy immediately.
*
* @category NomCatégorie
* @package NomPaquetage
* @author Auteur original <auteur@example.com>
* @author Un autre author <autre@example.com>
* @copyright 1997-2005 The PHP Group
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version CVS: $Id:$
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since File available since Release 1.2.0
* @deprecated File deprecated in Release 2.0.0
*/
/**
* Placez ici les includes, les définitions de constantes
* et les configurations des $_GLOBAL.
* Assurez-vous d'ajouter les commentaires
* docblocks pour éviter que phpDocumentor
* assume qu'elles sont documentées dans les commentaires générals du fichier.
*/
/**
* Description courte de la classe
*
* Description plus détaillée de la classe (si besoin en est)...
*
* @category NomCatégorie
* @package NomPaquetage
* @author Auteur original <auteur@example.com>
* @author Un autre author <autre@example.com>
* @copyright 1997-2005 The PHP Group
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version Release: @package_version@
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class foo
{
}
?>
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 :
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.
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.
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.
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.
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:
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.
