Share
À ce stade de la série, nous avons couvert beaucoup de matériel - non seulement les bases de la programmation orientée objet, mais nous avons également commencé à créer un plugin entièrement fonctionnel..
Cependant, le travail que nous avons accompli jusqu’à présent pose un problème, car il ne contient aucune documentation sur le fonctionnement réel du plug-in. Si vous vous souvenez de l'article précédent, nous avons pris une décision de développement conscient de reporter cette fonctionnalité..
À partir de cet article, nous allons examiner en deux parties comment documenter les plugins WordPress et comment le faire, étant donné notre plugin actuel..
Avant de continuer avec le reste de cet article, je vous encourage vivement à rattraper le contenu que nous avons couvert jusqu'à présent. Comme mentionné dans tous les articles précédents, chaque article est basé sur l'article précédent de la série.
Cela dit, il est temps de concentrer notre attention sur la documentation de notre plugin, mais avant de le faire, nous devons nous assurer de bien comprendre les normes en vigueur pour documenter notre travail..
Donc, avant de fournir les commentaires pertinents pour notre plugin, nous allons examiner ce que nous devons inclure. Après cela, nous verrons exactement comment faire cela pour notre plugin dans le prochain article.
Pour commencer, le codex WordPress comprend un manuel spécifique aux normes de documentation PHP. Vous pouvez lire les normes dans leur intégralité; Cependant, nous allons souligner les caractéristiques les plus importantes de ce que nous allons mettre en œuvre dans le prochain article..
Les principales choses que nous documentons sont les suivantes:
Accentsconagua
exiger des déclarationsCe sera évidemment un ensemble d’articles beaucoup plus lents que les deux précédents, mais étant donné le volume de travail que nous avons couvert jusqu’à présent, cela devrait constituer un changement de rythme bienvenu pour certains lecteurs..
Donc, avec cela dit, commençons.
Les en-têtes de fichiers sont uniques dans le fait qu’ils sont quelque chose qui devrait être placé dans chaque fichier des fichiers qui constituent un plugin (ou un thème, mais ce n'est pas l'objet de cette série), mais ils ne sont pas toujours.
Selon le Codex:
Le bloc d’en-tête de fichier PHPDoc est utilisé pour donner un aperçu de ce qui est contenu dans le fichier..
Le modèle général que nous utiliserons à partir du prochain article se présente comme suit:
/ ** * Description courte (pas de période pour les en-têtes de fichier) * * Description longue. * * @link URL * @since x.x.x (si disponible) * * @package WordPress * @subpackage Component * /
Notez que dans les en-têtes de fichier, nous faisons ne pas inclure une période et il y a deux composants de la description:
Chaque fois que je les écris pour mes projets spécifiques, j'essaie d'imaginer que ma brève description, si quelque chose peut entrer dans le haut de LISEZMOI fichier, qui peut être un seul, court pas d'ascenseur pour le fichier, ou que peut même être contenu dans quelque chose d'aussi court qu'un tweet.
La description longue, bien entendu, peut être aussi facilement détaillée que nous le souhaitons. Dans ce cas, il existe un format spécifique que nous devrions utiliser pour une description longue, mais cela dépasse le cadre de cet article, car nous verrons un exemple concret et concret dans le prochain article de la série..
exiger Les déclarationsNous avons parfois besoin de documenter du code inclus dans une fonction ou une classe. Celles-ci sont différentes des définitions de fonction ou des définitions de variable de classe.
Pensez-en plutôt à des commentaires en ligne lorsque vous devez inclure ou nécessiter une certaine dépendance. Ce sera généralement un script PHP séparé sur toute autre chose.
Par exemple:
/** * Brève description. (use period) * / require_once (ABSPATH. '/filename.php');
Cependant, notez que, selon le Codex, cela est ne pas juste limité à des appels de fonction tels que Demandez une fois.
Les fichiers requis ou inclus doivent être documentés avec une courte description du bloc PHPDoc. Cela peut éventuellement s'appliquer aux appels inline get_template_part (), au besoin, par souci de clarté..
Comme notre plugin appelle directement des scripts externes, nous volonté utiliser un exemple pratique de cela dans le prochain article. La raison pour laquelle je le partage ici, ce n'est pas seulement pour nous préparer à ce qui s'en vient, mais aussi pour montrer le format approprié pour en tirer parti dans tous les courants que nous pourrions être en train de faire..
Bien que je pense que toute la documentation est importante, et je ne prétends pas que ces deux aspects sont la partie la plus importante de la documentation d'un plugin; Cependant, étant donné que notre plugin est par nature orienté objet, il est essentiel de comprendre comment documenter correctement nos classes et nos fonctions..
Les définitions de classe sont des commentaires de code qui apparaissent entre les en-têtes de fichier (décrits plus haut) et le nom de la classe..
Le format utilisé pour documenter une classe est le suivant:
/** * Brève description. (période d'utilisation) * * Description longue. * * @since x.x.x * * @see Fonction / méthode / classe basée sur * @link URL * /
Si vous consultez le codex WordPress pour cet article, vous remarquerez qu’il fournit une peu plus d'informations que j'ai inclus dans la documentation ci-dessus. C’est parce qu’ils ont inclus le contenu à la fois et définitions de fonction.
Au lieu de cela, nous les répartissons dans des zones distinctes pour référence future, afin de comprendre pourquoi nous allons documenter certaines choses de certaines manières dans le prochain article de la série..
Semblable aux définitions de classe, vous pouvez vous attendre à voir ce qui suit:
/** * Brève description. (période d'utilisation) * * Description longue. * * @since x.x.x * @access (pour les fonctions: à utiliser uniquement si privé) * * @see Fonction / méthode / classe basée sur * URL @lien * @global type $ nom_var Description succincte. * * @param type $ var Description. * @param type $ var Facultatif. La description. * Type de retour Description. * /
Remarquez dans le commentaire de code ci-dessus, il y a très peu de différence avec ce que nous avons vu avec la documentation de classe.
En plus de ce qui précède, nous voyons des informations sur:
Évidemment, ce matériel n'est pas généralement utilisé dans le contexte d'une classe; Cependant, il est utilisé dans le contexte d'une fonction.
À cette fin, voici comment vous pouvez penser à chacun de ce qui précède:
global Les variables font référence aux variables utilisées dans le contexte de la fonction qui sont globales pour l'environnement WordPress. Cela inclut des choses telles que $ post, $ authordata, et d'autres énumérés ici.@param tag fait référence aux variables acceptées par une fonction. Évidemment, cela inclut le type de variable qu’elle accepte et une description de ce que la variable représente.@revenir La balise traite du type de variable renvoyée par une fonction et d'une brève description du type de données renvoyées..Plutôt que de donner un exemple concret de ceci ici, nous le ferons dans le post suivant avec le code que nous avons écrit dans le post précédent.
Enfin, les propriétés de variable - ou plus communément appelées propriétés de classe (parfois appelées attributs), représentent les données contenues dans la classe..
Rappelez-vous, plus tôt dans notre série, nous avons mentionné que les attributs sont comme les adjectifs qui décrivent le nom que représente la classe.
Comme vous pouvez le voir dans l’article précédent, les propriétés de classe sont définies juste après le nom de la classe et avant le constructeur (peu importe si sa Publique ou privé).
Pour documenter ces attributs, nous suivons le modèle suivant:
/** * Brève description. (période d'utilisation) * * @since x.x.x * @access (privé, protégé ou public) * @var type $ var Description. * /
Assez facile à comprendre.
Certains pourraient soutenir que l’utilisation de @accès est frivole puisque le modificateur d'accès de la fonction qui suit directement le commentaire explique le type de fonction.
Mais c’est là que les différences entre les normes de documentation WordPress diffèrent de certaines des normes PHP (en place et en cours de normalisation)..
En bref, PSR fait référence aux recommandations standard de PHP telles que proposées par PHP Framework Interop Group.
Vous pouvez lire sur chacune de ces normes ici:
Quel PSR-5 est en cours de discussion. Celles-ci sont importantes à suivre pour tous les développeurs PHP, quelle que soit la plate-forme ou la fondation qu’ils utilisent, mais j’estime également que les différences (et similitudes) existant entre les normes PSR et WordPress sont les mêmes. sont différences.
C'est un point de désaccord, donc ce que je vais dire est purement subjectif; Cependant, je suis d’avis que, lorsque vous travaillez dans WordPress, vous devez respecter les conventions proposées par WordPress..
Cela ne veut pas dire que nous ne devrions pas faire un effort pour nous aligner plus étroitement sur ce que fait la communauté PHP dans son ensemble; Cependant, si nous écrivons du code WordPress pour d’autres développeurs WordPress, c’est quelque chose sur lequel nous devrions avant tout nous concentrer..
Dans le prochain article, nous allons examiner l'application des principes ci-dessus dans le contexte de notre plugin..
Cela devrait nous aider non seulement à construire un plugin hautement conforme aux normes de codage WordPress, mais également aux normes de documentation permettant à nos utilisateurs et à nos futurs contributeurs de suivre facilement le flux de contrôle tout au long du projet..
En attendant, n'hésitez pas à laisser des questions et / ou des commentaires dans le flux ci-dessous!
