PHPDocumentor es una herramienta escrita en PHP para programas PHP con anotaciones estándar, puede generar rápidamente documentos API con referencias cruzadas, indexación y otras funciones. La versión anterior es phpdoc.
1. ¿Qué es phpDocumentor?
PHPDocumentor es una herramienta escrita en PHP para programas PHP con anotaciones estándar, puede generar rápidamente documentos API con referencias cruzadas, indexación y otras funciones. La versión anterior es phpdoc. A partir de 1.3.0, se le cambió el nombre a phpDocumentor. La nueva versión agrega soporte para la sintaxis php5. Al mismo tiempo, los documentos se pueden generar operando en el navegador del cliente y los documentos se pueden convertir a. PDF, HTML. Hay varias formas de CHM, que son muy convenientes.
Cuando PHPDocumentor funciona, escaneará el código fuente PHP en el directorio especificado, escaneará las palabras clave, interceptará los comentarios que deben analizarse, luego analizará las etiquetas especiales en los comentarios, generará un archivo xml y luego, en función de la información de las clases y módulos analizados, establece los índices correspondientes, genera archivos xml y utiliza plantillas personalizadas para generar archivos en el formato especificado para los archivos xml generados.
2. Instale phpDocumentor
Al igual que otros módulos de Pear, la instalación de phpDocumentor también se divide en dos métodos: instalación automática e instalación manual. Ambos métodos son muy convenientes:
a. Instalar automáticamente a través de Pear e ingresar en la línea de comando
pera instalar PhpDocumentor
b. Instale manualmente la última versión de PhpDocumentor (ahora 1.4.0) en http://manual.phpdoc.org/ y descomprima el contenido.
3． Cómo utilizar PhpDocumentor para generar la línea de comando de documentación:
En el directorio donde se encuentra phpDocumentor, ingrese
Php-h
Obtendrá una lista detallada de parámetros, varios de los cuales son importantes:
-f El nombre del archivo a analizar, varios archivos separados por comas
-d Directorio a analizar, varios directorios separados por comas
-t ruta de almacenamiento del documento generado
-o El formato del documento de salida, la estructura es formato de salida: nombre del convertidor: directorio de plantilla.
Por ejemplo: phpdoc -o HTML:frames:earthli -f test.php -t docs
La interfaz web se genera en el nuevo phpdoc. Además de generar documentos en la línea de comando, también puede generar documentos en el navegador del cliente. El método específico es colocar primero el contenido de PhpDocumentor en el directorio de Apache. accedido a través del navegador, se mostrará la siguiente interfaz después del acceso:
Haga clic en el botón de archivos para seleccionar los archivos o carpetas php que se procesarán. También puede ignorar el procesamiento de ciertos archivos especificando Archivos a ignorar en esta interfaz.
Luego haga clic en el botón de salida para seleccionar la ruta de almacenamiento y el formato del documento generado.
Finalmente, haga clic en crear y phpdocumentor comenzará a generar documentos automáticamente. El progreso y el estado de la generación se mostrarán en la parte inferior.
Tiempo total de documentación: 1 segundo
hecho
¡¡Operación completada!!
Luego, podemos ver el documento generado. Si está en formato pdf, el nombre predeterminado es documentación.pdf.
4. Agregar comentarios estándar al código php
PHPDocument genera documentos a partir de comentarios en su código fuente, por lo que el proceso de comentar su programa es también el proceso de compilar documentación.
Desde este punto de vista, PHPdoc le anima a desarrollar buenos hábitos de programación y a intentar utilizar especificaciones y texto claro para anotar su programa. Al mismo tiempo, evita más o menos algunos problemas de desincronización entre la preparación del documento y el documento. actualizaciones posteriores.
En phpdocumentor, los comentarios se dividen en comentarios de documentación y comentarios que no son de documentación.
Los llamados comentarios de documentación son comentarios de varias líneas colocados delante de palabras clave específicas. Las palabras clave específicas se refieren a palabras clave que pueden analizarse mediante phpdoc, como clase, var, etc. Para obtener más detalles, consulte el Apéndice 1.
Los comentarios que no preceden a las palabras clave o que no están estandarizados se denominan comentarios sin documentación. Estos comentarios no serán analizados por phpdoc y no aparecerán en el texto API que genere.
3.2 Cómo escribir comentarios de documentación:
Todos los comentarios de la documentación son comentarios de varias líneas que comienzan con /**, que en phpDocumentor se denomina DocBlock y se refiere a la información de ayuda sobre una determinada palabra clave escrita por los desarrolladores de software para que otros puedan conocer el propósito específico de las palabras clave. y cómo utilizarlos. PhpDocumentor especifica que un DocBlock contiene la siguiente información:
1. Área de descripción breve de la función
2. Área de descripción detallada
3. Etiqueta
La primera línea del comentario de la documentación es el área de descripción de la función. El texto generalmente explica brevemente la función de esta clase, método o función. El texto de la descripción de la función se mostrará en el área de índice del documento generado. El contenido del área de descripción de la función puede terminar con una línea en blanco o. Después del área de descripción de la función, hay una línea en blanco, seguida de un área de descripción detallada. Esta parte describe principalmente la función y el propósito de su API en detalle. también puedes Ejemplos de uso, etc. En esta sección, debe centrarse en aclarar el propósito general y el uso de las funciones o métodos de su API, e indicar si es multiplataforma (si está involucrado). Para la información relacionada con la plataforma, debe tratarla de manera diferente a la información general. el enfoque habitual es comenzar una nueva línea y luego escribir las precauciones o información especial en una plataforma específica. Esta información debería ser suficiente para que sus lectores puedan escribir la información de prueba correspondiente, como condiciones de contorno, rangos de parámetros, puntos de interrupción, etc.
Después de eso, también hay una línea en blanco y luego la etiqueta del documento, que indica información técnica, principalmente el tipo de parámetro de llamada, el valor y tipo de retorno, la relación de herencia, los métodos/funciones relacionados, etc.
Con respecto al marcado de documentos, consulte la Sección 4: Marcado de documentos para obtener más detalles.
Etiquetas como <b> <código> también se pueden utilizar en los comentarios del documento. Consulte el Apéndice 2 para obtener más detalles.
El siguiente es un ejemplo de un comentario de documentación
/**
* Función sumar, implementa la suma de dos números
*
* Un cálculo de suma simple, la función acepta dos números a y b, y devuelve su suma c
*
* @param int sumando
* @param int sumando
* @return entero
*/
función Agregar ($a, $b) {
devolver $a+$b;
}
El documento generado es el siguiente:
Agregar
entero Sumar(int $a, int $b)
[línea 45]
Función suma, implementa la suma de dos números.
Constantes es un cálculo de suma simple. La función acepta dos números ayb y devuelve su suma c.
Parámetros
• int $a - sumando
• int $b - sumando
5. Etiquetas de documentos:
El alcance de uso de una etiqueta de documento se refiere a las palabras clave u otras etiquetas de documento que la etiqueta se puede utilizar para modificar.
Todas las etiquetas de documentación comienzan con @ después del * en cada línea. Si la marca @ aparece en medio de un párrafo, la marca se tratará como contenido normal y se ignorará.
@acceso
Ámbito de uso: clase, función, var, definir, módulo
Esta etiqueta se utiliza para indicar los derechos de acceso de la palabra clave: privado, público o protegido.
@autor
Especifique el autor
@derechos de autor
Ámbito de uso: clase, función, var, definir, módulo, uso
Especificar información de derechos de autor
@obsoleto
Ámbito de uso: clase, función, var, definir, módulo, contenido, global, incluir
Indicar palabras clave no utilizadas u obsoletas
@ejemplo
Esta etiqueta se utiliza para analizar una parte del contenido del archivo y resaltarlo. Phpdoc intentará leer el contenido del archivo desde la ruta del archivo proporcionada por esta etiqueta.
@const
Ámbito de uso: definir
Se utiliza para indicar las constantes definidas en php.
@final
Ámbito de uso: clase, función, var
Indica que la palabra clave es una clase, método o atributo final y está prohibido derivarla o modificarla.
@archivofuente
Similar al ejemplo, excepto que esta etiqueta leerá directamente el contenido del archivo php actualmente analizado y lo mostrará.
@global
Indica las variables globales a las que se hace referencia en esta función.
@ingore
Se utiliza para ignorar palabras clave específicas en el documento.
@licencia
Equivalente a <a> en la etiqueta html, primero está la URL, luego el contenido que se mostrará, como <a href="http://www.baidu.com">Baidu</a>
Puedes escribir @license http://www.baidu.com Baidu
@enlace
similar a la licencia
Pero también puedes señalar cualquier palabra clave del documento a través del enlace.
@nombre
Especifique un alias para la palabra clave.
@paquete
Ámbito de uso: nivel de página -> definir, funcionar, incluir
Nivel de clase->clase, var, métodos
Se utiliza para agrupar lógicamente una o varias palabras clave en un grupo.
@abstrcut
Indica que la clase actual es una clase abstracta.
@param
Especificar los parámetros de una función.
@devolver
Especifica el puntero de retorno de un método o función.
@estático
Indica que la palabra clave es estática.
@var
Especificar tipo de variable
@versión
Especificar información de versión
@hacer
Indicar áreas que deberían mejorarse o no implementarse
@lanzamientos
Indica la excepción de error que puede generar esta función. En casos extremos, como se mencionó anteriormente, las etiquetas de documentos comunes deben marcarse con @ al comienzo de cada línea. Además, también hay una etiqueta llamada etiqueta en línea, que se usa {@}. , incluyendo específicamente lo siguiente:
{@enlace }
El uso es el mismo que @link.
{@fuente }
Mostrar el contenido de una función o método.
6． Algunas especificaciones de anotación
a. El comentario debe ser
/**
* XXXXXXX
*/
forma
b. Para funciones que hacen referencia a variables globales, se debe utilizar la etiqueta glboal.
c. Para las variables, su tipo debe estar marcado con var (int, string, bool...)
d. La función debe indicar sus parámetros y valor de retorno a través de etiquetas param y return.
e. Para las palabras clave que aparecen dos o más veces, ignore las redundantes hasta el final y conserve solo una.
f. Cuando se llamen a otras funciones o clases, se deben utilizar enlaces u otras etiquetas para vincular a la parte correspondiente para facilitar la lectura del documento.
g. Utilice comentarios que no sean de documentación cuando sea necesario para mejorar la legibilidad del código.
h. Mantenga el contenido descriptivo conciso y directo, utilizando frases en lugar de oraciones siempre que sea posible.
i. Las variables globales, las variables estáticas y las constantes deben declararse con las etiquetas correspondientes.
7. Resumen
phpDocumentor es una herramienta de generación automática de documentos muy poderosa. Puede ayudarnos a escribir comentarios estandarizados y generar documentos estructurados claros y fáciles de entender, lo cual es muy útil para nuestras actualizaciones de código, mantenimiento, transferencia, etc.
Para una descripción más detallada de phpDocumentor, puedes ir a su sitio web oficial.
http://manual.phpdoc.org/Ver
8. Apéndice Apéndice 1:
Palabras clave reconocidas por phpdoc:
Incluir
Requerir
incluir_una vez
requerir_una vez
definir
función
global
clase
Apéndice 2
Etiquetas que se pueden utilizar en documentos.
<b>
<código>
<br>
<kdb>
<li>
<pre>
<ul>
<muestra>
<var>
Apéndice 3:
Un fragmento de código php con comentarios canónicos:
<?php
/**
* Archivo de muestra 2, inicio rápido de phpDocumentor
*
* Este archivo demuestra la rica información que se puede incluir en
* Documentación en código a través de DocBlocks y etiquetas.
* @autor Greg Beaver < [email protected] >
* @versión 1.0
* @paquete de muestra
*/
// archivo de muestra #1
/**
* Valor de inclusión ficticio, para demostrar el poder de análisis de phpDocumentor
*/
include_once 'muestra3.php';
/**
* Declaración de variable global especial DocBlock
* @global entero $GLOBALS['_myvar']
* @nombre $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*Constantes
*/
/**
* primera constante
*/
definir('prueba', 6);
/**
* segunda constante
*/
define('otra constante', strlen('hola'));
/**
* Un bloque de documentos de función de muestra
* @global string documenta el hecho de que esta función usa $_myvar
* @staticvar entero $staticvar esto es en realidad lo que se devuelve
* @param cadena $param1 nombre a declarar
* @param cadena $param2 valor del nombre
* @return entero
*/
function firstFunc($param1, $param2 = 'opcional') {
estático $varatura estática = 7;
global $_myvar;
devolver $varatura estática;
}
/**
* La primera clase de ejemplo, está en el mismo paquete que el
*cosas procesales al inicio del archivo
* @paquete de muestra
* @subpaquete de clases
*/
clase miclase {
/**
* Una variable privada de muestra, que se puede ocultar con --parseprivate
*opción
* @accesoprivado
* @var entero|cadena
*/
var $primeravar = 6;
/**
* @link http://www.example.com Enlace de ejemplo
* @ver miclase()
* @usa pruebas, otra constante
* matriz @var
*/
var $segundovar =
formación(
'cosas' =>
formación(
6,
17,
'armadillo'
),
prueba => otra constante
);
/**
* El constructor configura {@link $firstvar}
*/
función miclase() {
$this->primeravar = 7;
}
/**
* Devuelve una cosa basada en $paramie
* @param booleano $paramie
* @return entero|babyclass
*/
function parentfunc($paramie) {
si ($paramie) {
devolver 6;
} demás {
devolver nueva clase de bebé;
}
}
}
/**
* @paquete muestra1
*/
clase babyclass extiende miclase {
/**
* La respuesta a la Vida, el Universo y Todo
* @var entero
*/
var $segundavar = 42;
/**
* Valores de configuración
* matriz @var
*/
var $tercera var;
/**
* Llama al constructor principal, luego incrementa {@link $firstvar}
*/
función clasebebé() {
padre::miclase();
$this->primeravar++;
}
/**
* Esto siempre devuelve un myclass
* @param ignoró $paramie
* @return miclase
*/
function parentfunc($paramie) {
devolver nueva miclase;
}
}
?>