PHPDoc

La versión actual de la página aún no ha sido revisada por colaboradores experimentados y puede diferir significativamente de la versión revisada el 28 de agosto de 2019; las comprobaciones requieren 5 ediciones .

PHPDoc es un estándar de documentación Javadoc  adaptado para su uso en PHP .

Descripción

Si bien el estándar de comentarios tiene solo un estado formal, sin embargo, se planea consolidarlo como uno de los estándares de desarrollo para los marcos PHP desarrollados por el grupo PHP-FIG. El estándar que se está preparando recibirá el número PSR-5 [1] . PHPDoc es compatible con código procedimental y orientado a objetos en los documentos.

Se ha creado un programa phpDocumentor separado para interpretar el código .

phpDocumentor es una aplicación capaz de analizar el código fuente de PHP y los comentarios de DocBlock para generar un conjunto completo de documentación API [2] .

Componentes de PHPDoc

Bloques de documentos

Los doc-blocks ( eng.  DocBlock comments ) son comentarios de varias líneas en el estilo del lenguaje C , ubicados antes del elemento documentado. El primer carácter de un comentario (y al comienzo de las líneas de comentario) debe ser * . Los bloques están separados por líneas en blanco.

Un ejemplo de bloque Doc para la función foo():

/** * @param string $msg string para generar * @author WikiEditor * @copyright 2016 Wikipedia * @return string sin cambios */ function foo ( $msg = '' ) { return $msg ; }

Características de PHPDoc

  1. Soporte para la última versión de PHP
  2. Trabajar con clases de diagrama UML
  3. Búsqueda de texto completo
  4. Soporte de CI listo para usar
  5. Más control con DocBlocks

Versiones de PHPDoc

Versión actual de PHPDocumentator 3, Repositorio

Funciones

  • Compatible con PHP 7.0+ , soporte completo para espacios de nombres, bucles y más.
  • Docblock sobre tipos , docblocks es más explícito sobre los tipos, no todos los formatos son compatibles con php.
  • Representa 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 inferior a 20 MB, para proyectos medianos es de 40 MB y para marcos grandes es de 100 MB.
  • Análisis incremental. Al guardar un archivo de estructura de una ejecución anterior, hay un aumento de rendimiento adicional de hasta un 80 % además del aumento de la velocidad de procesamiento mencionado anteriormente.
  • La simple creación de una plantilla hace posible llamar a 1 tarea y editar 3 archivos.
  • Proceso de dos pasos  : phpDocumentor primero crea un caché con la estructura de la aplicación antes de generar la salida. Le permite utilizar sus propias herramientas o formateadores.
  • Soporte general , con más análisis estático en php, los tipos se han vuelto más complejos. phpDocumentor entiende estos tipos. Y los mostrará como tipos de primera clase [2] .

Aplicación

Al desarrollar sus propios proyectos grandes, todas las sutilezas de las cuales no se pueden tener en cuenta, al igual que al finalizar los proyectos de otras personas, a menudo tiene que echar un vistazo al código escrito previamente. Esto le permite imaginar con mayor precisión los objetos creados y devueltos y lo que puede hacer con ellos. Dado que PHP tiene una conversión de tipos implícita , es posible que se produzcan errores cuando se realizan operaciones en objetos de diferentes tipos. En lenguajes fuertemente tipados , esto no sucederá, el programa simplemente no se compilará.

Para evitar esto, se utilizan PHPDoc y otras tecnologías similares. Digamos que tenemos un código :

... $eventData = new EventData (); $eventData -> remitente = $controlador ; $eventData -> nombre = 'onDelete' ; $eventData -> grupo = 'global' ; $eventData -> argumentos = matriz ( 'id' => 15 ); $eventDispatcher -> triggerEvent ( $eventData ); ...

Es posible que un desarrollador externo que lea este código no sepa qué contiene $controller, pero el IDE le dirá si es compatible con PHPDoc. Es decir, tecleando: $controller->- podemos ver lo que hay dentro. Como resultado, no hay necesidad de profundizar en la jungla de código para averiguar qué pasa por este objeto y en qué tipo.

Enlaces

Notas

  1. ↑ fig-standards/phpdoc.md phpDocumentor/fig-standards // GitHub . Fecha de acceso: 20 de diciembre de 2015. Archivado desde el original el 31 de marzo de 2016.
  2. ↑ 1 2 Centro acoplable . hub.docker.com _ Recuperado: 24 de septiembre de 2022.