Share
En este punto de la serie, hemos cubierto una gran cantidad de material: no solo hemos cubierto los conceptos básicos de la programación orientada a objetos, sino que también hemos comenzado a crear un complemento totalmente funcional..
Pero el desafío que viene con el trabajo que hemos hecho hasta ahora es que no incluye ninguna documentación sobre cómo funciona realmente el complemento. Si recuerda el artículo anterior, tomamos una decisión de desarrollo consciente para posponer esta función.
A partir de este artículo, veremos cómo documentar los complementos de WordPress y cómo podemos hacerlo, dado nuestro complemento actual..
Antes de continuar con el resto de este artículo, le recomiendo que se ponga al día con el contenido que hemos cubierto hasta ahora. Como se mencionó en todos los artículos anteriores, cada artículo se basa en el artículo anterior de la serie..
Dicho esto, es hora de centrar nuestra atención en documentar nuestro complemento, pero antes de seguir adelante y hacer eso, debemos asegurarnos de que comprendemos completamente los estándares que tenemos para documentar nuestro trabajo..
Entonces, antes de proporcionar los comentarios que son relevantes para nuestro complemento, vamos a echar un vistazo a todo lo que necesitamos incluir. Después de eso, veremos cómo hacer exactamente eso para nuestro complemento en el siguiente artículo..
Para empezar, el Códice de WordPress incluye un manual específicamente para los Estándares de Documentación de PHP. Puedes leer las normas en su totalidad; Sin embargo, vamos a destacar las características más importantes de lo que vamos a implementar en el próximo artículo..
Las principales cosas que nos preocupan documentar son las siguientes:
Accentsconagua
exigir declaracionesObviamente, este será un conjunto de artículos mucho más lento que los dos anteriores, pero dada la cantidad de trabajo que hemos cubierto hasta ahora, debería ser un cambio de ritmo bien recibido para algunos lectores..
Así que con eso dicho, vamos a empezar.
Los encabezados de archivo son únicos en el hecho de que son algo que debería colocarse en cada archivo de los archivos que conforman un complemento (o un tema, pero ese no es el enfoque de esta serie), pero no siempre son.
Según el Códice:
El bloque de encabezado del archivo PHPDoc se usa para dar una visión general de lo que está contenido en el archivo.
La plantilla general que usaremos a partir del siguiente artículo se verá así:
/ ** * Descripción breve (sin período para encabezados de archivo) * * Descripción larga. * * @link URL * @since x.x.x (si está disponible) * * @package WordPress * @subpackage Component * /
Tenga en cuenta que en los encabezados de archivo, hacemos no Incluye un período y hay dos componentes de la descripción:
Cada vez que escribo esto para mis proyectos específicos, trato de imaginar que mi breve descripción, si algo que puede encajar en la parte superior de Leer archivo, que puede ser un solo paso corto de ascensor para el archivo, o que mayo Incluso estar contenido en algo tan corto como un tweet.
La descripción más larga, por supuesto, puede ser tan fácilmente más detallada como queramos. En este caso, hay un formato específico que deberíamos usar para una descripción larga, pero eso está fuera del alcance de este artículo en particular, como veremos un ejemplo práctico particular en el próximo artículo de la serie..
exigir DeclaracionesOcasionalmente, tenemos la necesidad de documentar el código que se incluye en una función o una clase. Estas son diferentes a las definiciones de funciones o definiciones de variables de clase.
En su lugar, piense en estos como comentarios en línea para cuando necesite incluir o requerir una cierta dependencia. Esto generalmente será un script PHP aparte sobre cualquier otra cosa..
Por ejemplo:
/** * Breve descripción. (use period) * / require_once (ABSPATH. '/filename.php');
Sin embargo, tenga en cuenta que de acuerdo con el Codex que esto es no Sólo limitado a llamadas de función tales como requerir una vez.
Los archivos requeridos o incluidos deben documentarse con una breve descripción del bloque PHPDoc. Opcionalmente, esto puede aplicarse a las llamadas inline get_template_part () según sea necesario para mayor claridad.
Dado que nuestro complemento realiza llamadas directamente a scripts externos, será Estaré usando un ejemplo práctico de esto en el próximo artículo. La razón por la que lo comparto aquí no es solo para prepararnos para lo que viene, sino también para mostrar el formato adecuado de cómo aprovechar esto en cualquier corriente que podamos estar haciendo..
Aunque creo que toda la documentación es importante, y no estoy afirmando que estos dos aspectos sean la parte más importante de la documentación de un complemento; Sin embargo, dado que nuestro complemento está orientado a objetos en su naturaleza, es clave que entendamos cómo documentar adecuadamente nuestras clases y nuestras funciones..
Las definiciones de clase son comentarios de código que aparecen entre los encabezados de los archivos (que hemos analizado anteriormente) y el nombre de la clase.
El formato que se utiliza para documentar una clase es el siguiente:
/** * Breve descripción. (período de uso) * * Descripción larga. * * @since x.x.x * * @ver Función / método / clase basada en * @ link URL * /
Si observa el Códice de WordPress para este artículo, notará que proporciona una pequeño Más información que he incluido en la documentación anterior. Esto es porque han incluido contenido tanto de clase como de clase. y definiciones de funciones.
En su lugar, estamos dividiendo cada una de ellas en áreas separadas para futuras referencias, y para que podamos ver por qué documentaremos ciertas cosas de ciertas maneras en el próximo artículo de la serie..
Similar a las definiciones de clase, que puede esperar ver lo siguiente:
/** * Breve descripción. (período de uso) * * Descripción larga. * * @since x.x.x * @access (para funciones: usar solo si es privado) * * @ver Función / método / clase en la que se confía * @ URL de enlace * @global type $ varname Descripción breve. * * @param type $ var Descripción. * @param type $ var Opcional. Descripción. * Descripción del tipo @return. * /
Observe que en el comentario de código anterior, hay muy poca diferencia con lo que vimos con la documentación de la clase..
Además de lo que está arriba, vemos información para:
Obviamente, este material no se usa normalmente dentro del contexto de una clase; De todos modos, eso es utilizado dentro del contexto de una función.
Para ese fin, aquí está cómo puedes pensar en cada uno de los anteriores:
global las variables se refieren a aquellas variables que se utilizan en el contexto de la función que son globales para el entorno de WordPress. Esto incluye cosas tales como $ post, $ authordata, y otros listados aquí.@param etiqueta se refiere a las variables que una función acepta. Obviamente, esto incluye el tipo de variable que acepta y una descripción de lo que representa la variable.@regreso la etiqueta analiza el tipo de variable que devuelve una función y una breve descripción del tipo de datos que se devuelven.En lugar de dar un ejemplo concreto de esto aquí, lo haremos en la publicación de seguimiento con el código que escribimos en la publicación anterior.
Finalmente, las propiedades variables, o más comúnmente conocidas como propiedades de clase (que a veces se denominan atributos), representan los datos que se mantienen dentro de la clase.
Recuerde que anteriormente en nuestra serie, mencionamos que los atributos son como los adjetivos que describen el sustantivo que la clase representa.
Como puede ver en el artículo anterior, las propiedades de la clase se definen justo después del nombre de la clase y antes del constructor (independientemente de si está público o privado).
Para documentar estos atributos, seguimos la siguiente plantilla:
/** * Breve descripción. (período de uso) * * @since x.x.x * @access (privado, protegido o público) * @ var tipo $ var Descripción. * /
Lo suficientemente fácil de entender.
Algunos pueden argumentar que el uso de @acceso es frívolo ya que el modificador de acceso de la función que sigue directamente al comentario explica el tipo de función que es.
Pero aquí es donde las diferencias en los estándares de documentación de WordPress difieren de algunos de los estándares de PHP (tanto los existentes como los que están en proceso de estandarización).
En resumen, PSR hace referencia a las recomendaciones estándar de PHP según lo propuesto por PHP Framework Interop Group.
Puedes leer sobre cada uno de estos estándares aquí:
Qué PSR-5 se está discutiendo en este momento. Estos son importantes para todos los desarrolladores de PHP, independientemente de la plataforma o la base que estén utilizando, pero también creo que vale la pena señalar que las diferencias (y similitudes) existentes entre el PSR y los estándares de WordPress existen. son diferencias.
Este es un punto de desacuerdo, por lo que lo que voy a decir es puramente subjetivo; Sin embargo, soy de la mentalidad de que cuando trabajas en WordPress, debes seguir las convenciones propuestas por WordPress..
Esto no quiere decir que no debemos hacer un esfuerzo para alinearnos más estrechamente con lo que está haciendo la comunidad PHP en general; Sin embargo, si estamos escribiendo el código de WordPress para otros desarrolladores de WordPress, entonces esto es algo en lo que debemos centrarnos principalmente..
En el siguiente artículo, veremos cómo aplicar los principios anteriores en el contexto de nuestro complemento..
Esto nos debería ayudar no solo a crear un complemento que se ajuste a los estándares de codificación de WordPress, sino también a los estándares de documentación de modo que nosotros, nuestros usuarios y nuestros futuros contribuyentes podamos seguir fácilmente el flujo de control a lo largo del proyecto..
Mientras tanto, no dude en dejar sus preguntas y / o comentarios en el feed a continuación.!
