phpDocumentor
v3.5.3
phpDocumentor se erige como la herramienta de documentación de facto para proyectos PHP y ofrece una solución sólida para generar documentación completa sin esfuerzo. Al analizar su código fuente PHP y los comentarios de DocBlock, phpDocumentor genera un conjunto completo de documentación API, lo que lo convierte en una herramienta indispensable para los desarrolladores que buscan bases de código claras y bien documentadas.
Más allá de su destreza en la documentación de API, phpDocumentor va más allá al proporcionar funciones adicionales. Está equipado con la capacidad de crear diagramas UML, lo que la convierte en una herramienta versátil para visualizar la estructura del código. Además, phpDocumentor ofrece un analizador de lenguaje de marcado con todas las funciones, que admite la sintaxis de RestructuredText y Markdown. Esta flexibilidad le permite documentar su proyecto utilizando el lenguaje de marcado que mejor se adapte a sus preferencias.
Una característica notable de phpDocumentor es su capacidad de incluir partes de su documentación API directamente en su documentación de RestructuredText. Esta integración garantiza que su documentación y código permanezcan sincronizados, lo que le ahorra tiempo y esfuerzo a la hora de mantener una documentación del proyecto precisa y actualizada.
Inspirado por sus predecesores, phpDocumentor 1 y JavaDoc, phpDocumentor continúa innovando y manteniéndose actualizado con las últimas tecnologías y características del lenguaje PHP. Este compromiso garantiza que los desarrolladores tengan acceso a la mejor experiencia de documentación posible, en línea con las prácticas de desarrollo modernas.
En esta guía, exploraremos las diversas características de phpDocumentor, desde su funcionalidad principal para generar documentación API hasta sus capacidades avanzadas para analizar lenguajes de marcado. Ya sea que sea un principiante o un desarrollador experimentado, phpDocumentor es su aliado en la creación de proyectos PHP bien documentados, fáciles de mantener y comprensibles.
v3 es la última versión estable.
Para obtener información más detallada, puede consultar nuestra documentación en línea en https://docs.phpdoc.org/.
phpDocumentor soporta lo siguiente:
Compatible con PHP 7.0+ , se proporciona soporte completo para espacios de nombres, cierres y más.
Docblock sobre tipos , docblocks puede ser más explícito acerca de los tipos, no todos los formatos son compatibles con PHP nativo.
Muestra cualquier etiqueta , algunas etiquetas agregan funcionalidad adicional a phpDocumentor (como @link).
Bajo uso de memoria , el uso máximo de memoria para proyectos pequeños es de menos de 20 MB, proyectos medianos de 40 MB y marcos grandes de 100 MB.
Análisis incremental : si conservó el archivo de estructura de una ejecución anterior, obtendrá un aumento de rendimiento adicional de hasta un 80 % además del aumento de velocidad de procesamiento mencionado anteriormente.
Fácil construcción de plantillas , si quieres hacer una marca solo tienes que llamar a 1 tarea y editar 3 archivos.
Proceso de dos pasos , phpDocumentor primero genera un caché con la estructura de su aplicación antes de crear la salida. ¡Si lo deseas, puedes usarlo para potenciar tus propias herramientas o formateadores!
El soporte de genéricos , con análisis más estáticos en los tipos de php, se ha vuelto más complejo. phpDocumentor comprende estos tipos. Y los representará como tipos de primera clase.
PhpDocumentor requiere PHP 8.1 o superior para ejecutarse. Sin embargo, se puede analizar el código de versiones anteriores de PHP.
Todas las plantillas proporcionadas con phpDocumentor tienen soporte para diagramas de clases basados en el código base de lectura. Esto requerirá que la aplicación [PlantUml] esté instalada en la máquina que ejecuta phpDocumentor. Representar los diagramas de clases usando [PlantUml] es opcional y las advertencias sobre la falta de [PlantUml] se pueden ignorar. Sin embargo, en este caso su documentación contendrá algunos enlaces inactivos. El diagrama de clases se creará con la opción --setting=graphs.enabled=true .
Hay 4 formas de instalar phpDocumentor:
Usando Phive (recomendado)
Usando PHAR (instalación manual)
A través de Docker
Vía compositor
$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42
Para obtener más información sobre Phive, visite su sitio web. Ahora que tienes instalado phpDocumentor, puedes ejecutarlo así:
php tools/phpDocumentor
Descargue el archivo phar desde https://github.com/phpDocumentor/phpDocumentor/releases
Puedes ejecutar el phar así: php phpDocumentor.phar
$ docker pull phpdoc/phpdoc
$ docker run --rm -v $(pwd):/data phpdoc/phpdoc
¿Pero espera? ¿Qué pasa con el compositor?
Ah, descubriste nuestro secreto. Existe un paquete de compositor phpdocumentor que puede utilizar para instalar phpDocumentor.
Sin embargo: phpDocumentor es una aplicación compleja y sus bibliotecas se utilizan en muchas otras bibliotecas y aplicaciones (2 de nuestras bibliotecas tienen más de 150 millones de descargas cada una); y esto significa que las posibilidades de que se produzca un conflicto entre una de nuestras dependencias y la suya son altas. Y cuando digo alto, es realmente alto.
Entonces, debido a lo anterior: no respaldamos ni apoyamos activamente la instalación de phpDocumentor usando Composer.
La forma más sencilla de ejecutar phpDocumentor es ejecutando el siguiente comando:
$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>
Este comando analizará el código fuente proporcionado utilizando el argumento -d y lo enviará a la carpeta indicada por el argumento -t .
phpDocumentor admite una amplia gama de opciones para configurar la salida de su documentación. Puede ejecutar el siguiente comando o consultar nuestro sitio web para obtener una lista más detallada de las opciones de línea de comandos disponibles.
$ phpdoc run -h
phpDocumentor también admite el uso de archivos de configuración (llamados phpdoc.xml o phpdoc.dist.xml de forma predeterminada). Consulte la documentación para ver el formato y las opciones admitidas.
PhpDocumentor no tiene lanzamientos nocturnos. Sin embargo, durante cada canalización se construye un artefacto phar. Si desea probar la versión más avanzada de phpDocumentor, eche un vistazo a la sección de acciones de este repositorio. Cada flujo de trabajo de control de calidad exitoso tiene una sección de Artefactos en la parte inferior con el artefacto phar creado.
Comunicarse con nosotros es fácil y se puede hacer con:
Gorjeo: @phpDocumentor
Sitio web: https://www.phpdoc.org
GitHub: https://www.github.com/phpDocumentor/phpDocumentor
Correo electrónico: [email protected]
