@package & @subpackage: cómo usar con temas secundarios

8

Mi problema es con @packagey @subpackage.

Fui al enlace sugerido ( ¿Para qué son los comentarios del paquete y el subpaquete? ). Allí no encontré nada que pudiera aplicar a mi problema, sino esta respuesta: “Estas son etiquetas PHPDoc, utilizadas para generar documentación de código significativa (y automatizada)”. Esto es lo que tengo ahora:

/**

* 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

*/

Este no es un tema secundario de veinte diez. Hay una carpeta en la carpeta del tema-name: functions. El tema de mi hijo está en otra carpeta. He guardado el functions.phparchivo en la carpeta de temas de mi hijo. No sucede nada (cambiar el contenido) cuando cambio el subpaquete del nombre de mi carpeta o dejo la Functionspalabra allí.

¿Qué debería poner aquí?

/**

* 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 ???

*/
child-theme Marie
fuente

Respuestas:

4

Tal como dice la documentación original que encontró, estas son etiquetas PHPDocumenter. No afectan su código en absoluto, por lo que cambiarlos no hará nada.

Sin embargo, son útiles para herramientas automatizadas que analizan su código y crean documentación legible para humanos. Este PHPXref es un ejemplo de una versión analizada de WordPress.

En WordPress, el @packagees típicamente WordPress. El @subpackagees cualquier módulo que estés viendo. Entonces, por ejemplo, la parte superior de la WP_Httpclase contiene:

/**
 * 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
 */

En su caso, @packagesería el nombre de su tema. @subpackagees opcional y solo es realmente relevante si tiene otros módulos dentro de su tema; su functions.phparchivo no es realmente un subpaquete del tema, por lo que omitiría la etiqueta en ese caso.

Los temas secundarios tampoco tienen que heredar la estructura @package/ @subpackagede sus padres. Use lo que tiene sentido para su proyecto porque, en realidad, estos comentarios y notas son específicos para ayudar a otros a comprender la estructura de su proyecto.

EAMann
fuente
Hola, gracias a todos por sus respuestas. Acabo de dejar el nombre del paquete con el nombre de ellos (espero haberlo entendido correctamente). El archivo .php que tengo está en una carpeta de funciones en mi tema secundario como en el tema principal. No he podido hacer que funcione, así que pensé que el problema estaba en la forma en que el paquete y el subpaquete se referían a otros elementos. No es el caso de lo que dices y de cómo todavía no funciona. ¿Cómo hago para que funcione el archivo .php, por favor? (¿O debería ser un nuevo hilo?)
Marie
¿Está utilizando include()o require()en su functions.phparchivo principal para incluir el nuevo archivo PHP? De lo contrario, nunca se cargará. Diría que abrir un nuevo hilo, pero incluir archivos PHP no es un problema específico de WP; por lo que si haces abierto un nuevo hilo me animo a hacerlo desbordamiento de pila.
EAMann
4

Regla general: ¿está su código incluido (es decir, empaquetado ) con el código que indique @package? Si no, está utilizando un valor incorrecto para @package.

Para el caso de la mayoría de los temas, esto es fácil:

  • Los temas incluidos en el núcleo usan @package: WordPressy @subpackage Theme-Name, porque están empaquetados y distribuidos con WordPress
  • Todos los demás temas se usan @package: Theme-Nameporque están empaquetados y distribuidos por separado de WordPress.

Todos los temas son una capa de abstracción de WordPress y dependen de WordPress para su salida. Pero esa dependencia no los convierte en un @subpackageWordPress.

También aplicaría esta regla a los Temas infantiles. Son un paquete independiente, empaquetado y distribuido por separado del tema principal / plantilla en el que se basan.

Chip Bennett
fuente
1

Esas son etiquetas de documentación. Los utiliza para agrupar bits de código relacionados a los fines de la documentación del código. Wikipedia tiene una buena tabla con las diferentes etiquetas disponibles. La documentación oficial está en http://www.phpdoc.org/ .

No sucede nada (cambiar el contenido) cuando cambio el subpaquete del nombre de mi carpeta o dejo la palabra "Funciones" allí.

Derecha. No pasa nada. Esto es solo para la documentación del código. No notará nada hasta que ejecute su código a través del script PHPDoc, que generará documentación pero no cambiará el funcionamiento de su código.

Úselo @packagepara identificar su tema. Use @subpackage, si lo desea, para agrupar funciones dentro del tema, digamos un archivo lleno de widgets específicos del tema o algo así.

¿Qué diferencia hace incluir la anotación @package o no?

http://codex.wordpress.org/Inline_Documentation

s_ha_dum
fuente