@package & @subpackage: comment utiliser les thèmes enfants
Mon problème est avec @package et @subpackage.
Je suis allé au lien suggéré ( À quoi servent les commentaires de paquet et de sous-paquetage? ). Là, je n'ai rien trouvé que je puisse appliquer à mon problème, mais plutôt la réponse suivante: "Ce sont des balises PHPDoc - utilisées pour générer une documentation de code significative (et automatisée)". Voici ce que j'ai maintenant:
/**
* Contains a list of all custom action hooks and corresponding functions defined for abc.
* This file is included in functions.php:
*
* @package theme-name
* @subpackage Functions
*/
Ce n'est pas un thème d'enfant de vingt-dix ans. Il existe un dossier dans le dossier nom-thème: functions. Le thème de mon enfant est dans un autre dossier. J'ai enregistré le fichier functions.php dans le dossier de mon thème enfant. Rien ne se passe (modification du contenu) lorsque je modifie le nom de mon dossier ou que je laisse le mot Functions ici.
Que devrais-je mettre ici?
/**
* Contains a list of all custom action hooks and corresponding functions defined for abc.
* This file is included in functions.php:
*
* @package theme-name
* @subpackage ???
*/
Tout comme la documentation originale que vous avez trouvée, il s'agit de balises PHPDocumenter. Ils n'ont aucun impact sur votre code, donc les changer ne fera rien.
Cependant, ils sont utiles pour les outils automatisés qui analysent votre code et créent une documentation lisible par l'homme. Cette PHPXref est un exemple de version analysée de WordPress.
Dans WordPress, le @package est généralement WordPress. Le @subpackage est le module que vous regardez. Ainsi, par exemple, la partie supérieure de la classe WP_Http contient:
/**
* Simple and uniform HTTP request API.
*
* Standardizes the HTTP requests for WordPress. Handles cookies, gzip encoding and decoding, chunk
* decoding, if HTTP 1.1 and various other difficult HTTP protocol implementations.
*
* @link http://trac.wordpress.org/ticket/4779 HTTP API Proposal
*
* @package WordPress
* @subpackage HTTP
* @since 2.7.0
*/
Dans votre cas, @package serait le nom de votre thème. @subpackage est facultatif et ne concerne vraiment que si vous avez d'autres modules dans votre thème - votre fichier functions.php n'est pas vraiment un sous-package du thème, donc j'omettrais la balise dans ce cas.
Les thèmes enfants ne doivent pas non plus hériter de la structure @package/@subpackage de leurs parents. Utilisez ce qui a du sens pour votre projet car, en réalité, ces commentaires et notes sont spécifiques pour aider les autres à comprendre la structure de votre projet.
Règle générale: votre code est-il groupé (c'est-à-dire empaqueté ) avec le code quelconque indiqué par @package? Si non, vous utilisez une valeur incorrecte pour @package.
Pour la plupart des thèmes, c'est simple:
- Core-bundled Themes utilise
@package: WordPresset@subpackage Theme-Name, car ils sont emballés et distribués avec WordPress lui-même - Tous les autres thèmes utilisent
@package: Theme-Name, car ils sont emballés et distribués séparément à partir de WordPress.
Tous les thèmes sont une couche d’abstraction de WordPress et reposent sur WordPress pour la sortie. Mais cette dépendance ne fait pas d'eux un @subpackage de WordPress.
J'appliquerais également cette règle aux thèmes pour enfants. Ils constituent un package autonome, empaqueté et distribué séparément à partir du thème parent/modèle sur lequel ils s'appuient.
Le @package spécifie un package pour regrouper des classes ou des fonctions et définit également un thème pour WordPress. Un @subpackage est un enfant du thème, comme une fonctionnalité pour une exigence spécifique ou un thème enfant, un sous-package.
petit indice pour la doc des tags phpdoc: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html
Ce sont des balises de documentation. Vous les utilisez pour regrouper des bits de code associés à des fins de documentation sur le code. Wikipedia a un bon graphique avec les différentes balises disponibles. La documentation officielle est à http://www.phpdoc.org/ .
Rien ne se passe (modification du contenu) lorsque je change de nom de dossier ou que je laisse le mot "Fonctions" ici.
Droite. Rien ne se passe. Ceci est pour la documentation de code seulement. Vous ne remarquerez rien jusqu'à ce que vous exécutiez votre code via le script PHPDoc, qui générera de la documentation mais ne changera pas le fonctionnement de votre code.
Utilisez @package pour identifier votre thème. Utilisez @subpackage, si vous le souhaitez, pour regrouper des fonctions dans le thème, par exemple un fichier contenant des widgets spécifiques à un thème ou quelque chose du genre.
Quelle différence cela fait-il d'inclure ou non l'annotation @package?