Introduction au phpdoc

Points de base

• phpdoc (phpDocumentor) est un outil puissant qui aide les développeurs à écrire des documents de code via des annotations de format spécial. Il peut générer des documents dans plusieurs formats, tels que HTML, PDF et CHM, qui peuvent être extraits via une interface Web ou une interface de ligne de commande.
• PHPDOC utilise DocBlocks (commentaires de style C multi-lignes) pour documenter les blocs de code. DocBlocks contient trois parties facultatives: une brève description, une description détaillée et une balise. La balise commence par le symbole @, qui spécifie des informations supplémentaires sur le code.
• Le package PHPDOC est utilisé pour regrouper les éléments de code pertinents dans le document généré. Vous pouvez spécifier des packages pour les fichiers et les classes à l'aide des balises @package et @subpackage dans le docblock au niveau du fichier ou au niveau de la classe.
• PHPDOC peut écrire des documents pour divers éléments de code, y compris les fichiers, les classes, les fonctions et les méthodes, les propriétés de classe, les variables globales, include()/require() et define(). Ces éléments peuvent utiliser certaines balises communes, mais chacune a une balise spécifique.
• L'outil de ligne de commande de PHPDOC est utilisé pour générer des documents conviviaux basés sur le code PHP qui a été écrit. Cet outil offre une variété de formats de documents. Pour les utilisateurs qui ne connaissent pas l'interface de ligne de commande, PHPDOC fournit également une interface Web.

Le code de lecture écrit par d'autres (qui ne l'a pas vécu?) Est une tâche difficile. Le "code de style pâtes" désordonné est mélangé à un grand nombre de variables étrangement nommées, ce qui le rend étourdi. Cette fonction attend-elle des chaînes ou des tableaux? Cette variable stockait-elle des entiers ou des objets? Après d'innombrables heures de suivi du code et d'essayer de comprendre les fonctionnalités de chaque partie, il est courant d'abandonner et de réécrire l'intégralité du code à partir de zéro - c'est une perte de temps précieux. PHPDOC (le nom court pour PhpDocumentor) est un outil puissant qui vous permet d'écrire facilement des documents de code avec des commentaires dans des formats spéciaux. Les documents sont non seulement disponibles dans le code source, mais également des documents professionnels extraits via l'interface Web ou l'interface de ligne de commande. Le résultat peut être dans une variété de formats tels que HTML, PDF et CHM. De plus, de nombreux IDE qui fournissent l'achèvement du code peuvent analyser les commentaires PHPDOC et fournir des fonctionnalités pratiques telles que des invites de type. En utilisant PHPDOC, vous pouvez faciliter la compréhension de votre code, même après des semaines, des mois ou même des années après l'avoir écrit. La façon la plus simple d'installer PHPDOC est d'utiliser la poire. Bien sûr, la poire doit être installée avant de le faire. Si vous n'avez pas d'installation de poire, suivez les instructions sur Pear.php.net/manual/en/installation.php. Dans cet article, je vais vous montrer comment générer de beaux documents conviviaux du début à la fin avec PHPDOC.

docblocks

DOCBLOCK est un commentaire de style C multi-lignes utilisé pour écrire des documents pour les blocs de code. Il commence par /** et chaque ligne a un astérisque. Voici un exemple:

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

docblocks contient trois parties: une brève description, une description détaillée et une étiquette. Les trois parties sont facultatives. Une brève description est une description concise qui se termine par une nouvelle ligne ou une période. La routine analytique de PHPDOC est intelligente; Une description détaillée est le contenu principal d'un document; Les descriptions détaillées et les descriptions courtes peuvent contenir certains éléments HTML pour la mise en forme. Les balises HTML non soutenues seront affichées en texte brut. PHPDOC peut générer des documents dans plusieurs formats, donc les balises HTML ne rendent pas nécessairement comme elles le font dans les fichiers HTML; Si vous devez afficher les balises HTML en tant que texte, utilisez des supports doubles. Par exemple:

<?php
/**
 * 这里是斜体标签的示例： >Hello, world!>
 */

La section de balise de

docblock contient n'importe quel nombre de balises spéciales représentées par le symbole @. Les balises sont utilisées pour spécifier des informations supplémentaires, telles que les paramètres attendus et leurs types. La plupart des balises doivent être sur leurs propres lignes, mais certaines balises peuvent être inclinées. Les balises en ligne sont enfermées en accolades bouclées et peuvent apparaître dans des descriptions détaillées et des descriptions brèves. Pour une liste complète des balises, consultez la documentation PHPDOC pertinente. Si vous avez besoin d'une ligne pour commencer par le symbole @ mais que vous ne voulez pas l'interpréter comme une étiquette, vous pouvez y échapper avec une barre oblique inverse. PHPDOC identifiera et analysera automatiquement la liste de texte dans la description détaillée et la brève description. Cependant, il n'analyse pas correctement les listes imbriquées. Si vous souhaitez utiliser des listes imbriquées, utilisez des balises HTML. Voici un exemple pour illustrer ce que je veux dire:

<?php
/**
 * 使用列表的示例
 *
 * PhpDoc 将正确解析此列表：
 * - 项目 #1
 * - 项目 #2
 * - 项目 #3
 *
 * 但不是这个列表：
 * - 项目 1
 *   - 项目 1.1
 *   - 项目 1.2
 * - 项目 2
 *
 * 请改用此方法创建嵌套列表：
 * 

*

项目 1

*

*

项目 1.1

*

项目 1.2

* *

项目 2

* */

(Le contenu suivant sera brièvement résumé en raison des limitations de l'espace et des informations clés conservées)

sac

Le package PHPDOC est utilisé pour regrouper les éléments de code pertinents dans le document généré. Vous pouvez spécifier des packages pour les fichiers et les classes contenant du code écrit pour hériter de ces packages. Pour spécifier un package, définissez la balise @package dans le docblock au niveau du fichier ou au niveau de la classe. (Docblocks au niveau du fichier et au niveau de la classe sera discuté plus loin dans la section suivante). Les noms de packages peuvent contenir des lettres, des numéros, des tiret, des soulignements et des supports carrés ("[" et "]"). Voici un exemple de la définition d'un package de fichiers:

<?php
/**
 * 这是一个文件级 DocBlock
 *
 * @package Some_Package
 */

Si vous avez plusieurs niveaux de packages et de sous-packages, vous pouvez utiliser la balise @subpackage pour définir des sous-packages. Voici un exemple:

<?php
/**
 * 这是一个类级 DocBlock
 *
 * @package    Some_Package
 * @subpackage Other
 */
class SomeClass {
}

Si le fichier ou la classe ne spécifie pas de package, il sera défini sur le package par défaut "par défaut". Vous pouvez spécifier d'autres packages à utiliser par défaut via l'option de ligne de commande -dn.

Quels documents peuvent être écrits?

Tous les éléments de code ne peuvent pas être écrits à l'aide de DocBlocks. Voici une liste d'éléments de code qui peuvent être écrits dans le document:

• fichier
• catégorie
• Fonctions et méthodes
• Attributs de classe
• Variables globales
• include()/require()
• define()

Tous ces éléments peuvent utiliser certaines étiquettes communes, mais chaque élément a une étiquette spécifique à cet élément. Je couvrirai certains éléments et balises qui sont généralement utilisés pour écrire de la documentation pour eux.

(Les exemples de documentation de fichiers, classes, fonctions et méthodes seront brefs, seules les descriptions de balises clés seront conservées)

Générer un document

Après avoir écrit la documentation de votre code PHP, vous devez en générer des documents conviviaux. Pour ce faire, exécutez l'outil de ligne de commande PHPDOC.

<?php
/**
 * 计算数组中每个元素的平方和
 *
 * 循环遍历数组中的每个元素，将其平方，并将其添加到总和中。返回总和。
 *
 * 此函数也可以使用 array_reduce() 实现；
 *
 * @param array $arr
 * @return int
 * @throws Exception 如果数组中的元素不是整数
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

(La description du paramètre de ligne de commande sera brève)

Pour les utilisateurs qui ne connaissent pas l'interface de ligne de commande, PHPDOC fournit également une interface Web. Ce document n'en discute pas en détail, mais vous pouvez en savoir plus sur le site officiel de PHPDOC, phpdoc.org.

Résumé

Dans cet article, je vous présente PHPDOC et ses nombreuses fonctionnalités puissantes. J'ai expliqué le but de DocBlocks et de ses composants; Je vous recommande fortement de commencer à utiliser PHPDOC dans votre propre projet, même s'il s'agit simplement d'écrire la documentation pour les pièces les plus importantes. C'est très simple et peut vous sauver, ainsi qu'à vos collègues, d'innombrables heures de tension et de douleur.

(La section FAQ sera des questions de base brèves et conserves)

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!