Esta pagina es el inicio del esfuerzo para añadir documentación integrada al código fuente del núcleo de WordPress para ayudar en el desarrollo futuro, cambios, mejoras, y asistir a otros en su aprendizaje de PHP y WordPress.
Uso de esta pagina y paginas dependientes esta indicado para desarrollar metodologías y formatos comunes, así como para asegurarse de no duplicar esfuerzos. En el mejor de los casos, documentación integrada debe aparecer lo mas cercano posible a esto: PEAR sample.
Documentar globales proporciona información para phpDocumentor y otros leyendo el código fuente acerca del uso como el global es usado. No es requerido y en muchas ocasiones no es necesario, ya que los desarrolladores principales puede que no acepten los parches.
Funciones y métodos de clases por lo regular son difíciles de explicar sin contexto. Documentación puede ofrecer contexto, pero documentación integrada no debe ser usada para proveer ejemplos extremos, exceptuando para cortas lineas de código acerca de las cuales no hay información inmediata disponible en el codex.
La mayoría de las clases usadas en WordPress son Singletons (la funcionalidad entera es contenida en una única clase), pero seguido requieren inicialización manual de sus propiedades. Regularmente la pregunta de como usar un método en una clase no es clara.
Adiciones mas recientes y algunas bibliotecas externas usan clases múltiples para formarse a si mismas por funcionalidad. Esto crea una curva de aprendizaje mas pronunciada dado que la clase base (la que es usada por el desarrollador para proveer la funcionalidad desde el resto de las clases) no resulta clara. Añadir documentación acerca de donde cae la clase en la jerarquía proporciona mayor claridad.
Las propiedades de clases deben ser documentadas para tener una documentación completa. Las etiquetas PHPdoc para estas propiedades pueden ser encontrados en el sitio principal y un ejemplo puede ser encontrado abajo.
Estas etiquetas funcionan con algunos editores para mostrar mas información acerca de un segmento de código. Es útil para desarrolladores usando estos editores entender cual es el propósito de este código y como puede ser reusado con eficiencia.
La convención de permitir bloques en PHPdoc es para tener información @since disponible (aunque no este disponible en ese tiempo), e información @package que debe ser "WordPress" a menos que sea una biblioteca externa.
/**
* ... Descripción(es) aquí
*
* @package WordPress
* @since 2.1 or {{@internal Unknown}}}
*
* ... Se requiere mas información.
*/
Bloques de comentario PHPdoc no deben ser usados dentro de funciones y métodos, excepto para documentar información "TODO". Cualquier otro comentario dentro de funciones y métodos no debe usar estilos de PHPdoc.
/** * @todo ... Descripción */
La segunda forma puede ser usada de ser necesario:
/** @todo ... Descripción */
Esto es útil para explicar que relación el archivo a incluir tiene respecto al archivo actual, porque es necesario y que puede ser encontrado en el. No es necesario para archivos del núcleo de WordPress, pero puede servirte en tus propios Plugins si separas el codigo en archivos logicos.
/** * Este archivo contiene la información * personalizada para todos los usuarios */ require ABSPATH.'/wp-config.php';
Utilizar bloques de comentarios PHPdoc puede servir para proporcionar una vista general de lo que el archivo contiene. Obtener el máximo beneficio posible puede evitar que alguien se pierda en el código y desperdicie su tiempo
Algunas etiquetas de PHPdoc pueden ser aplicadas globalmente para cualquier otro bloque PHPdoc para sitios PHPDocumentor.
/** * ... Descripción de lo que este archivo contiene * * @package WordPress */
En muchas ocasiones es útil documentar globales comúnmente usadas por la función @uses.
Es mejor tener primero la descripción ya que por lo regular es lo que algún otro desarrollador necesita. El resto de la información puede ser importante (como @since) pero la etiqueta @global solamente es útil para sitios PHPDocumentor.
/** * ... Descripción * @since * @global type $varname */
La convención usada por funciones tipo PHPdoc en WordPress incluye una descripción corta y una descripción larga (de ser aplicable).
La descripción corta no debe recalcar el nombre de la función, sino mirar mas allá y aclarar lo que la función realiza y resumirla. El nombre de la función puede decir una cosa pero puede realizar algo completamente diferente.
La descripción corta es requerida para que la documentación de la función se considere completa. Una nota puede ser usada bajo ciertas circunstancias que le permita a otros saber que esta descripción no existe:
/** * Descripción Corta
Descripciones largas deben ser integradas en la mayoría de las funciones para despejar dudas acerca de la descripción corta. En la mayoría de los casos, el resumen debe funcionar como un recordatorio de lo que el desarrolador aprendió de la descripción larga.
Existen casos en que la funciona es tan pequeña que el resumen puede ser usado para describir por completo el propósito de la función. Esto se deja al criterio del autor de la documentación, pero como regla siempre hay que tratar de incluir descripciones largas en el bloque de PHPdoc.
/** * Descripción Corta * * Descripción Larga * */
Es aceptable si la función no tiene parámetros o documentación adicional que ambas descripciones son inexistentes. Esto solamente debe ser usado cuando se escribe documentación para funciones múltiples y estas dejando una nota para aclarar que se deja el hueco de manera intencional y que sera completado después.
/**
* {{@internal Descripción Corta faltante}}}
*
* {{@internal Descripción Larga faltante}}}
*
*/
En otras ocasiones, debe ser supuesto que si alguien dejo un hueco en la documentación fue por acción intencional, o por que consideraron que la descripción era necesaria para que otros entendieran la función o inclusive por que la documentación existe en alguno otro lugar. Como ejemplo esta la etiqueta @uses para variables globales, cuando la variable ya ha sido documentada
* @uses function_name() {{@internal Descripcion faltante}}}
* @uses function_name() {{@internal Descripcion faltante}}}
Después de las descripciones corta y larga, mas informacion es importante para el desarrollador y el sitio PHPdocumentor.
/** * Descripción Corta * * Descripción Larga * * @package WordPress * @since version * * @param type $varname Description * @return type Description */
La convención para la etiqueta @since es solamente usar el numero de version (como 2.1, 2.3 o 2.3.1) y nada mas. La información en @package proporciona la aplicación a la que la función pertenece.
Para mantener la consistencia, si existen parámetros para la función, estos también deben ser documentados. Si la palabra clave return es usada dentro de la función entonces la etiqueta @return debe ser usada para documentarlo. Si no existe debe ser dejado como esta.
Si la función es obsoleta o ya no tiene uso alguno, la etiqueta @deprecated deber usada, seguida de la version y la descripción de que usar en lugar de la función obsoleta. También hay que incluir la etiqueta @uses con el nombre de la función.
/** * ... Descripciones * * @deprecated 2.1 Usar funcion() en su lugar. * @uses funcion() * * ... parámetros y descripciones de retorno */
La informacion acerca de etiquetas clase PHPdoc por usarte en WordPress se deja fuera de manera intencional. De notarse es que la definicion de la clase, las propiedades (variables) de la clase y los métodos (funciones) de la clase deben ser documentados para considerarse completos.
El ejemplo PEAR debe ser usado como referencia.
La lista de correo WP-Hackers tiene un numero de discusiones acerca de como agregar documentación integrada. En casos recientes esta pagina no fue referenciada o usada durante la discusión. Al documentar archivos de WordPress, discusiones en WP-Hacker y otros lugares pueden ser evitadas a largo plazo
Para una lista actualizada en WordPress, favor de mirar en WordPress Files.
Bibliotecas proporcionadas por otras agencias deben tener documentación en cada archivo pero no forman parte del esfuerzo de documentación de WordPress. Los archivos que siguen tienen su propia documentación hasta la version 2.5 de WordPress y se encuentran en el directorio wp-includes.
Estos archivos se encuentran en la raíz de WordPress y se consideran completos.
Estos archivos se encuentran incompletos o se encuentran pendientes de inclusión al tronco principal de desarrollo. Algunos tienen funciones o clases por documentarse.
Estos archivos tienen documentación completa en el estilo de PHPdoc. Listados se encuentran el escritor de la documentación junto con su ticket en WordPress Trac.
Cada archivo debe ser marcado como un trabajo en progreso. Si deseas adoptar un archivo o funcion para documentación, favor de hacerlo y agregarlo a esta lista. Estos archivos ya se han comenzado y necesitan ser completados.
Los archivos existentes en los directorios wp-admin y wp-admin/includes aun deben ser documentados por completo. Los archivos en wp-admin necesitan documentación integrada de las funciones que contienen.
Los archivos en wp-admin/includes necesitan documentación integrada y todas sus funciones y clases tambien.
Este ticket es obsoleto ya que admin-functions.php ya no esta en uso en WordPress 2.5+, pero aun es util para funciones que fueron migradas al directorio wp-admin/includes.