PHPDocumentor est un outil écrit en PHP pour les programmes PHP avec des annotations standard, il peut générer rapidement des documents API avec des références croisées, une indexation et d'autres fonctions. L'ancienne version est phpdoc.
1. Qu'est-ce que phpDocumentor ?
PHPDocumentor est un outil écrit en PHP pour les programmes PHP avec des annotations standard, il peut générer rapidement des documents API avec des références croisées, une indexation et d'autres fonctions. L'ancienne version est phpdoc. À partir de la 1.3.0, elle a été renommée phpDocumentor. La nouvelle version ajoute la prise en charge de la syntaxe php5. En même temps, les documents peuvent être générés en opérant sur le navigateur client et les documents peuvent être convertis en. PDF, HTML, Il existe plusieurs formes de CHM, qui sont très pratiques.
Lorsque PHPDocumentor fonctionne, il analysera le code source PHP sous le répertoire spécifié, analysera les mots-clés, interceptera les commentaires qui doivent être analysés, puis analysera les balises spéciales dans les commentaires, générera un fichier XML, puis sur la base des informations de les classes et modules analysés, établissent les index correspondants, génèrent des fichiers XML et utilisent des modèles personnalisés pour générer des fichiers au format spécifié pour les fichiers XML générés.
2. Installez phpDocumentor
Comme les autres modules sous Pear, l'installation de phpDocumentor est également divisée en deux méthodes : l'installation automatique et l'installation manuelle. Les deux méthodes sont très pratiques :
un. Installez automatiquement via pear et entrez sur la ligne de commande
poire installer PhpDocumentor
b. Installez manuellement la dernière version de PhpDocumentor (maintenant 1.4.0) sur http://manual.phpdoc.org/ et décompressez le contenu.
3. Comment utiliser PhpDocumentor pour générer la ligne de commande de la documentation :
Dans le répertoire où se trouve phpDocumentor, saisissez
Php-h
Vous obtiendrez une liste détaillée des paramètres, dont plusieurs paramètres importants sont les suivants :
-f Le nom du fichier à analyser, plusieurs fichiers séparés par des virgules
-d Répertoire à analyser, plusieurs répertoires séparés par des virgules
-t chemin de stockage du document généré
-o Le format du document de sortie, la structure est format de sortie : nom du convertisseur : répertoire du modèle.
Par exemple : phpdoc -o HTML:frames:earthli -f test.php -t docs
L'interface web est générée dans le nouveau phpdoc. En plus de générer des documents sur la ligne de commande, vous pouvez également générer des documents sur le navigateur client. La méthode spécifique consiste à placer d'abord le contenu de PhpDocumentor dans le répertoire Apache afin qu'il puisse être généré. accessible via le navigateur, l'interface suivante s'affichera après l'accès :
Cliquez sur le bouton fichiers pour sélectionner les fichiers ou dossiers php à traiter. Vous pouvez également ignorer le traitement de certains fichiers en spécifiant Fichiers à ignorer dans cette interface.
Cliquez ensuite sur le bouton de sortie pour sélectionner le chemin de stockage et le format du document généré.
Enfin, cliquez sur créer, et phpdocumentor commencera automatiquement à générer des documents. La progression et l'état de la génération seront affichés en bas.
Temps total de documentation : 1 seconde
fait
Opération terminée !!
Ensuite, nous pouvons visualiser le document généré S'il est au format pdf, le nom par défaut est documentation.pdf.
4. Ajouter des commentaires standard au code php
PHPDocument génère des documents à partir des commentaires dans votre code source, donc le processus de commentaire sur votre programme est également le processus de compilation de la documentation.
De ce point de vue, PHPdoc vous encourage à développer de bonnes habitudes de programmation et à essayer d'utiliser des spécifications et du texte clair pour annoter votre programme. En même temps, cela évite plus ou moins certains problèmes de désynchronisation entre la préparation du document et le document. mises à jour par la suite.
Dans phpdocumentor, les commentaires sont divisés en commentaires de documentation et commentaires non liés à la documentation.
Les commentaires dits de documentation sont des commentaires multilignes placés devant des mots-clés spécifiques. Les mots-clés spécifiques font référence à des mots-clés qui peuvent être analysés par phpdoc, tels que classe, var, etc. Pour plus de détails, veuillez consulter l'annexe 1.
Les commentaires qui ne précèdent pas les mots-clés ou qui ne sont pas standardisés sont appelés commentaires de non-documentation. Ces commentaires ne seront pas analysés par phpdoc et n'apparaîtront pas dans le texte de l'API que vous générez.
3.2 Comment rédiger des commentaires sur la documentation :
Tous les commentaires de documentation sont des commentaires sur plusieurs lignes commençant par /**, appelés DocBlock dans phpDocumentor. DocBlock fait référence aux informations d'aide sur un certain mot-clé écrites par les développeurs de logiciels afin que d'autres puissent le connaître. Le but spécifique des mots-clés. et comment les utiliser. PhpDocumentor précise qu'un DocBlock contient les informations suivantes :
1. Zone de brève description de la fonction
2. Zone de description détaillée
3. Étiquette
La première ligne du commentaire de la documentation est la zone de description de la fonction. Le texte explique généralement brièvement la fonction de cette classe, méthode ou fonction. Le texte de la description de la fonction sera affiché dans la zone d'index du document généré. Le contenu de la zone de description de la fonction peut être terminé par une ligne vide ou. Après la zone de description de la fonction se trouve une ligne vide, suivie d'une zone de description détaillée. Cette partie décrit principalement la fonction et l'objectif de votre API en détail. vous pouvez également des exemples d'utilisation, etc. Dans cette section, vous devez vous concentrer sur la clarification de l'objectif général et de l'utilisation de vos fonctions ou méthodes API, et indiquer si elles sont multiplateformes (le cas échéant). Pour les informations relatives à la plate-forme, vous devez les traiter différemment des informations générales. l'approche habituelle consiste à démarrer une nouvelle ligne, puis à écrire les précautions ou les informations spéciales sur une plate-forme spécifique. Ces informations devraient être suffisantes pour que vos lecteurs puissent écrire les informations de test correspondantes, telles que les conditions aux limites, les plages de paramètres, les points d'arrêt, etc.
Après cela, il y a également une ligne vide, puis la balise du document, indiquant certaines informations techniques, principalement le type de paramètre d'appel, la valeur et le type de retour, la relation d'héritage, les méthodes/fonctions associées, etc.
Concernant le marquage des documents, veuillez vous référer à la section 4 : Marquage des documents pour plus de détails.
Des balises telles que <b> <code> peuvent également être utilisées dans les commentaires du document. Veuillez vous référer à l'annexe 2 pour plus de détails.
Ce qui suit est un exemple de commentaire de documentation
/**
* Fonction add, implémente l'addition de deux nombres
*
* Un simple calcul d'addition, la fonction accepte deux nombres a et b, et renvoie leur somme c
*
* @param int ajout
* @param int somme
* @return entier
*/
fonction Ajouter ($a, $b) {
retourner $a+$b;
}
Le document généré est le suivant :
Ajouter
entier Ajouter (int $a, int $b)
[ligne 45]
Fonction add, implémente l'addition de deux nombres
Les constantes sont un simple calcul d'addition. La fonction accepte deux nombres a et b et renvoie leur somme c.
Paramètres
• int $a - ajout
• int $b - somme
5. Balises du document :
Le domaine d'utilisation d'une balise de document fait référence aux mots-clés ou autres balises de document que la balise peut être utilisée pour modifier.
Toutes les balises de documentation commencent par @ après le * sur chaque ligne. Si la marque @ apparaît au milieu d'un paragraphe, la marque sera traitée comme un contenu normal et ignorée.
@accéder
Champ d'utilisation : classe, fonction, var, définition, module
Cette balise permet d'indiquer les droits d'accès du mot-clé : privé, public ou protégé
@auteur
Précisez l'auteur
@droit d'auteur
Champ d'utilisation : classe, fonction, var, définition, module, utilisation
Spécifier les informations de copyright
@obsolète
Champ d'utilisation : classe, fonction, var, définition, module, contenu, global, inclusion
Indiquer les mots-clés inutilisés ou obsolètes
@exemple
Cette balise est utilisée pour analyser un élément du contenu du fichier et le mettre en évidence. Phpdoc essaiera de lire le contenu du fichier à partir du chemin du fichier indiqué par cette balise.
@const
Domaine d'utilisation : définir
Utilisé pour indiquer les constantes définies en php
@final
Champ d'utilisation : classe, fonction, var
Indique que le mot-clé est une classe, une méthode ou un attribut final et qu'il est interdit de le dériver ou de le modifier.
@filesource
Semblable à l'exemple, sauf que cette balise lira directement le contenu du fichier php actuellement analysé et l'affichera.
@mondial
Indique les variables globales référencées dans cette fonction
@ingore
Utilisé pour ignorer les mots-clés spécifiés dans le document
@licence
Équivalent à <a> dans la balise html, il y a d'abord l'URL, puis le contenu à afficher, tel que <a href=”http://www.baidu.com”>Baidu</a>
Vous pouvez écrire @license http://www.baidu.com Baidu
@lien
similaire au permis
Mais vous pouvez également pointer vers n'importe quel mot-clé du document via un lien
@nom
Spécifiez un alias pour le mot-clé.
@emballer
Champ d'utilisation : niveau de la page -> définir, fonction, inclure
Niveau de classe -> classe, var, méthodes
Utilisé pour regrouper logiquement un ou plusieurs mots-clés dans un groupe.
@abstrcut
Indique que la classe actuelle est une classe abstraite
@param
Spécifier les paramètres d'une fonction
@retour
Spécifie le pointeur de retour d'une méthode ou d'une fonction
@statique
Indique que le mot-clé est statique.
@var
Spécifier le type de variable
@version
Spécifier les informations de version
@faire
Indiquer les domaines qui devraient être améliorés ou non mis en œuvre
@lancements
Indique l'exception d'erreur que cette fonction peut générer. Dans les cas extrêmes, comme mentionné ci-dessus, les balises de document ordinaires doivent être marquées avec @ au début de chaque ligne. De plus, il existe également une balise appelée balise en ligne, utilisant {@ } signifie. , notamment les éléments suivants :
{@lien }
L'utilisation est la même que @link
{@source }
Afficher le contenu d'une fonction ou d'une méthode
6. Quelques spécifications d'annotation
a. Le commentaire doit être
/**
* XXXXXXX
*/
formulaire
b. Pour les fonctions qui font référence à des variables globales, la balise glboal doit être utilisée.
c. Pour les variables, leur type doit être marqué par var (int, string, bool...)
d. La fonction doit indiquer ses paramètres et renvoyer la valeur via les balises param et return
e. Pour les mots-clés qui apparaissent deux fois ou plus, ignorez les redondants via ingore et n'en gardez qu'un.
f. Lorsque d'autres fonctions ou classes sont appelées, un lien ou d'autres balises doivent être utilisés pour créer un lien vers la partie correspondante afin de faciliter la lecture du document.
g. Utilisez des commentaires non liés à la documentation si nécessaire pour améliorer la lisibilité du code.
h. Gardez le contenu descriptif concis et précis, en utilisant des expressions plutôt que des phrases lorsque cela est possible.
i. Les variables globales, les variables statiques et les constantes doivent être déclarées avec les balises correspondantes.
7. Résumé
phpDocumentor est un outil de génération automatique de documents très puissant. Il peut nous aider à rédiger des commentaires standardisés et à générer des documents faciles à comprendre et clairement structurés, ce qui est très utile pour les mises à niveau de notre code, la maintenance, le transfert, etc.
Pour une description plus détaillée de phpDocumentor, vous pouvez vous rendre sur son site officiel
http://manual.phpdoc.org/View
8. Annexe Annexe 1 :
Mots clés reconnus par phpdoc :
Inclure
Exiger
include_once
require_once
définir
fonction
mondial
classe
Annexe 2
Balises pouvant être utilisées dans les documents
<b>
<code>
<br>
<kdb>
<li>
<pré>
<ul>
<échantillon>
<var>
Annexe 3 :
Un morceau de code php avec des commentaires canoniques :
<?php
/**
* Exemple de fichier 2, démarrage rapide de phpDocumentor
*
* Ce fichier démontre la richesse des informations qui peuvent être incluses dans
* Documentation dans le code via DocBlocks et balises.
* @auteur Greg Beaver < [email protected] >
* @version 1.0
* Échantillon de @package
*/
// exemple de fichier n°1
/**
* Valeur d'inclusion factice, pour démontrer la puissance d'analyse de phpDocumentor
*/
include_once 'sample3.php';
/**
* Déclaration spéciale de variable globale DocBlock
* @entier global $GLOBALS['_myvar']
* @name $_mavar
*/
$GLOBALS['_mavar'] = 6;
/**
*Constantes
*/
/**
* première constante
*/
définir('test', 6);
/**
* deuxième constante
*/
définir('une autre constante', strlen('bonjour'));
/**
* Un exemple de docblock de fonction
* @global string documente le fait que cette fonction utilise $_myvar
* @staticvar entier $staticvar c'est en fait ce qui est renvoyé
* @param string $param1 nom à déclarer
* @param string $param2 valeur du nom
* @return entier
*/
function firstFunc($param1, $param2 = 'facultatif') {
statique $staticvar = 7;
global $_myvar;
renvoie $varstatique ;
}
/**
* Le premier exemple de classe, il se trouve dans le même package que le
*éléments de procédure au début du fichier
* Échantillon de @package
* Classes @subpackage
*/
classe maclasse {
/**
* Un exemple de variable privée, celle-ci peut être masquée avec --parseprivate
*option
* @accessprivate
* @var entier|chaîne
*/
var $firstvar = 6;
/**
* @link http://www.example.com Exemple de lien
* @voir maclasse()
* @utilise les tests, une autre constante
* Tableau @var
*/
var $secondvar =
tableau(
'truc' =>
tableau(
6,
17,
'tatou'
),
test => une autre constante
);
/**
* Le constructeur configure {@link $firstvar}
*/
fonction maclasse() {
$this->firstvar = 7;
}
/**
* Renvoyez un truc basé sur $paramie
* @param booléen $paramie
* @return entier|classe bébé
*/
function parentfunc ($paramie) {
si ($paramie) {
retourner 6 ;
} autre {
renvoyer une nouvelle classe de bébé ;
}
}
}
/**
* @échantillon de package1
*/
la classe babyclass étend ma classe {
/**
* La réponse à la vie, à l'univers et à tout
* @var entier
*/
var $secondvar = 42;
/**
* Valeurs de configuration
* Tableau @var
*/
var $troisièmevar;
/**
* Appelle le constructeur parent, puis incrémente {@link $firstvar}
*/
fonction babyclass() {
parent::maclasse();
$this->firstvar++;
}
/**
* Cela renvoie toujours une myclass
* @param a ignoré $paramie
* @return maclasse
*/
function parentfunc ($paramie) {
renvoyer une nouvelle maclasse ;
}
}
?>