software plantilla para metodos libre herramientas fuente formato documentar documentacion codigo java php documentation javadoc phpdoc

java - metodos - plantilla para documentar codigo



Una herramienta para agregar y completar la documentación del código fuente PHP (9)

¿Desea realmente automatizar el problema de completar los datos de tipo "javadoc"?

El kit de herramientas de reingeniería de software de DMS podría configurarse para hacer esto.

Analiza el texto de origen tal como lo hacen los compiladores, construye estructuras internas del compilador, le permite implementar análisis arbitrarios, hacer modificaciones a esas estructuras y luego regenerar ("impresión bonita") el texto de origen cambiado de acuerdo con los cambios de estructura. Incluso conserva los comentarios y el formato del texto original; Por supuesto, puede insertar comentarios adicionales y aparecerán, y este parece ser su objetivo principal. DMS hace esto para muchos idiomas, incluyendo PHP

Lo que querría hacer es analizar cada archivo PHP, ubicar cada clase / método, generar los comentarios "javadoc" que deberían ser esa entidad (diferencia de clases y métodos, ¿verdad?) Y luego verificar que los comentarios correspondientes realmente estuvieran presentes en el Estructuras del compilador. Si no, simplemente insértelos. PrettyPrint el resultado final. Como tiene acceso a las estructuras del compilador que representan el código, no debería ser difícil generar parámetros y devolver información, como sugirió. Lo que no puede hacer, por supuesto, es generar comentarios sobre el propósito del objetivo ; pero podría generar un marcador de posición para que rellenes más tarde.

Tengo varios proyectos PHP terminados y más antiguos con muchos de los que me gustaría documentar en estilo javadoc / phpDocumentor.

Mientras que trabajar en cada archivo de forma manual y obligarme a hacer una revisión de código junto con la documentación sería lo mejor, estoy, por falta de tiempo, interesado en herramientas que me ayuden a automatizar la tarea tanto como sea posible.

La herramienta en la que estoy pensando tendría idealmente las siguientes características:

  • Analice un árbol de proyectos PHP y dígame dónde hay archivos, clases y funciones / métodos no documentados (es decir, los elementos que faltan en el comentario de bloque de documentos apropiado)

  • Proporcione un método para agregar a la mitad fácilmente los docblocks faltantes creando las estructuras vacías e, idealmente, abriendo el archivo en un editor (interno o externo, no me importa) para que pueda incluir la descripción.

Opcional:

  • Reconocimiento automático de tipos de parámetros, valores de retorno y similares. Pero eso no es realmente necesario.

El lenguaje en cuestión es PHP, aunque puedo imaginar que una herramienta C / Java podría manejar archivos PHP después de algunos ajustes.

Gracias por tu gran aportación!

Como PHPCS ya se mencionó, lanzo la API de Reflection para verificar si faltan DocBlocks. El artículo vinculado a continuación es un breve tutorial sobre cómo podría abordar su problema:

También hay un paquete PEAR PHP_DocBlockGenerator que puede crear el bloque de páginas del archivo y los DocBlocks para incluir variables globales, funciones, parámetros, clases, constantes, propiedades y métodos (y otras cosas).

Hace poco tuve que hacer un gran lote de automatización de la corrección de docblock, principalmente basada en la respuesta correcta anterior k con algunos cambios específicos del contexto. Es un truco, pero estoy enlazando aquí en caso de que sea útil para alguien más en el futuro. Esencialmente, realiza un análisis básico de tokens de bloque de comentarios dentro de PHP Beautifier.

https://gist.github.com/israelshirk/408f2656100196e73367

Las versiones 1.4.x de phpDocumentor tienen la opción -ue (--undocumentedelements) [1], lo que hará que los elementos no documentados aparezcan como advertencias en la página errors.html que genera durante su ejecución doc.

Además, parece que PHP_DocBlockGenerator [2] de PEAR puede generar docblocks faltantes para ti.

[1] - http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.undocumentedelements

[2] - http://pear.php.net/package/PHP_DocBlockGenerator

No tengo idea de si es de alguna ayuda, pero si Codesniffer puede señalar las funciones / métodos, entonces un IDE de PHP decente (ofrezco PHPEd) puede inspeccionar y estructurar fácilmente los comentarios de PHPDoc para cada función.

Simplemente escriba /** sobre cada función y presione ENTER, y PHPEd completará automáticamente el código con @param1 , @param1 , @return , etc. completado correctamente, listo para sus descripciones adicionales. Aquí está el primero que probé para dar un ejemplo:

/** * put your comment here... * * @param mixed $url * @param mixed $method * @param mixed $timeout * @param mixed $vars * @param mixed $allow_redirects * @return mixed */ public static function curl_get_file_contents($url, $method = ''get'', $timeout = 30, $vars = array(), $allow_redirects = true)

Esto se puede ajustar fácilmente a:

/** * Retrieves a file using the cURL extension * * @param string $url * @param string $method * @param int $timeout * @param array $vars parameters to pass to cURL * @param int $allow_redirects boolean choice to follow any redirects $url serves up * @return mixed */ public static function curl_get_file_contents($url, $method = ''get'', $timeout = 30, $vars = array(), $allow_redirects = true)

No es exactamente una solución automatizada, pero lo suficientemente rápida para mí como desarrollador perezoso :)

Puede usar el Code Sniffer for PHP para probar su código contra un conjunto predefinido de pautas de codificación. También comprobará si faltan docblocks y generará un informe que puede usar para identificar los archivos.

Usamos códigos para esta funcionalidad en el trabajo, usando estándares estándar PEAR o Zend. No le permitirá editar los archivos sobre la marcha, pero definitivamente le dará una lista, con líneas y descripción de qué tipo de docblock falta.

HTH, Jc

php-tracer-weaver puede instrumentar código y generar bloques de documentos con los tipos de parámetros, deducidos a través del análisis de tiempo de ejecución.

Creo que PHP_Codesniffer puede indicar cuando no hay docblock; vea los ejemplos de informes en esta página (citando uno de esos) :

-------------------------------------------------------------------------------- FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S) -------------------------------------------------------------------------------- 2 | ERROR | Missing file doc comment 20 | ERROR | PHP keywords must be lowercase; expected "false" but found | | "FALSE" 47 | ERROR | Line not indented correctly; expected 4 spaces but found 1 47 | WARNING | Equals sign not aligned with surrounding assignments 51 | ERROR | Missing function doc comment 88 | ERROR | Line not indented correctly; expected 9 spaces but found 6 --------------------------------------------------------------------------------

Supongo que podría usar PHP_Codesniffer para obtener al menos una lista de todos los archivos / clases / métodos que no tienen documentación; De lo que recuerdo, puede generar XML como salida, lo que sería más fácil de analizar utilizando una herramienta automatizada, que podría ser el primer paso de algunos docblock-generator ;-)


Además, si está utilizando phpDocumentor para generar la documentación, ¿puede este no reportar errores por bloques faltantes?

Después de un par de pruebas, puede, por ejemplo, ejecutarlo en un archivo de clase sin mucha documentación, con la opción --undocumentedelements , como esta:

phpdoc --filename MyClass.php --target doc --undocumentedelements

Da esto en el medio de la salida:

Reading file /home/squale/developpement/tests/temp/test-phpdoc/MyClass.php -- Parsing file WARNING in MyClass.php on line 2: Class "MyClass" has no Class-level DocBlock. WARNING in MyClass.php on line 2: no @package tag was used in a DocBlock for class MyClass WARNING in MyClass.php on line 5: Method "__construct" has no method-level DocBlock. WARNING in MyClass.php on line 16: File "/home/squale/developpement/tests/temp/test-phpdoc/MyClass.php" has no page-level DocBlock, use @package in the first DocBlock to create one done

Pero, aquí también, aunque sea útil como herramienta de informes, no es tan útil cuando se trata de generar los bloques de documentos que faltan ...


Ahora, no conozco ninguna herramienta que genere previamente los docblocks faltantes para usted: generalmente uso PHP_Codesniffer y / o phpDocumentor en mi mecanismo de integración continua, reporta docblocks faltantes y, luego, cada desarrollador agrega lo que falta. , desde su IDE ...

... Lo que funciona bastante bien: generalmente no faltan más de un par de docblocks cada día, por lo que la tarea se puede realizar a mano (y Eclipse PDT proporciona una función para generar previamente el docblock de un método, cuando usted está editando un archivo / método específico) .

Aparte de eso, no conozco ninguna herramienta totalmente automatizada para generar bloques de documentos ... Pero estoy bastante seguro de que podremos crear una herramienta interesante, ya sea utilizando:


Sin embargo, después de buscar un poco más, encontré esta publicación en el blog (está en francés, quizás algunas personas aquí podrán entender) : Ajout automatique of Tags phpDoc à l''aide de PHP_Beautifier .
Posible traducción del título: "Agregar automáticamente etiquetas phpDoc, usando PHP_Beautifier"

La idea en realidad no es mala:

  • La herramienta PHP_Beautifier es bastante agradable y potente, cuando se trata de formar un código PHP que no está bien formado.
    • Lo he usado muchas veces para código que ni siquiera pude leer ^^
  • Y se puede extender, usando lo que se llama " filtros ".

La idea que se usa en la publicación de blog a la que me he vinculado es:

  • cree un nuevo filtro PHP_Beautifier, que detectará los siguientes tokens:
    • T_CLASS
    • T_FUNCTION
    • T_INTERFACE
  • Y agregue un bloque de documentos "borrador" justo antes de ellos, si aún no hay uno


Para ejecutar la herramienta en algún archivo MyClass.php , primero PHP_Beautifier instalar PHP_Beautifier :

pear install --alldeps Php_Beautifier-beta

Luego, descargue el filtro al directorio en el que estaba trabajando (podría haberlo puesto en el directorio predeterminado, por supuesto) :

wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs cp phpDoc.filter.phpcs phpDoc.filter.php

Y, después de eso, creé un nuevo script beautifier-1.php (basado en lo que se propone en la publicación de blog a la que he vinculado, una vez más) , que:

  • Cargar el contenido de mi archivo MyClass.php
  • Instanciate PHP_Beautifier
  • Agrega algunos filtros para embellecer el código.
  • Agregue el filtro phpDoc que acabamos de descargar.
  • Embellece la fuente de nuestro archivo y hazlo con el resultado estándar.


Al código del script beautifier-1.php le gustará esto:
(Una vez más, la parte más importante es copiar y pegar de la publicación del blog; solo traduje los comentarios y cambié un par de cosas pequeñas)

require_once ''PHP/Beautifier.php''; // Load the content of my source-file, with missing docblocks $sourcecode = file_get_contents(''MyClass.php''); $oToken = new PHP_Beautifier(); // The phpDoc.filter.php file is not in the default directory, // but in the "current" one => we need to add it to the list of // directories that PHP_Beautifier will search in for filters $oToken->addFilterDirectory(dirname(__FILE__)); // Adding some nice filters, to format the code $oToken->addFilter(''ArrayNested''); $oToken->addFilter(''Lowercase''); $oToken->addFilter(''IndentStyles'', array(''style''=>''k&r'')); // Adding the phpDoc filter, asking it to add a license // at the beginning of the file $oToken->addFilter(''phpDoc'', array(''license''=>''php'')); // The code is in $sourceCode // We could also have used the setInputFile method, // instead of having the code in a variable $oToken->setInputString($sourcecode); $oToken->process(); // And here we get the result, all clean ! echo $oToken->get();

Tenga en cuenta que también tuve que phpDoc.filter.php dos cosas pequeñas en phpDoc.filter.php , para evitar una advertencia y un aviso ...
El parche correspondiente se puede descargar allí: http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch


Ahora, si ejecutamos ese script beautifier-1.php :

$ php ./beautifier-1.php

Con un archivo MyClass.php que inicialmente contiene este código:

class MyClass { public function __construct($myString, $myInt) { // } /** * Method with some comment * @param array $params blah blah */ public function doSomething(array $params = array()) { // ... } protected $_myVar; }

Este es el tipo de resultado que obtenemos, una vez que nuestro archivo está embellecido:

<?php /** * * PHP version 5 * * LICENSE: This source file is subject to version 3.0 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_0.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to [email protected] so we can mail you a copy immediately. * @category PHP * @package * @subpackage Filter * @author FirstName LastName <mail> * @copyright 2009 FirstName LastName * @link * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @version CVS: $Id:$ */ /** * @todo Description of class MyClass * @author * @version * @package * @subpackage * @category * @link */ class MyClass { /** * @todo Description of function __construct * @param $myString * @param $myInt * @return */ public function __construct($myString, $myInt) { // } /** * Method with some comment * @param array $params blah blah */ public function doSomething(array $params = array()) { // ... } protected $_myVar; }

Podemos observar:

  • El bloque de licencia al inicio del archivo.
  • El docblock que se ha agregado en la clase MyClass
  • El docblock que se ha agregado en el método __construct
  • El docblock en el doSomething ya estaba presente en nuestro código: no se ha eliminado.
  • Hay algunas etiquetas de @todo ^^


Ahora, no es perfecto, por supuesto:

  • No documenta todas las cosas que podríamos querer también
    • Por ejemplo, aquí, no documentó el protected $_myVar
  • No mejora los docblocks existentes.
  • Y no abre el archivo en ningún editor gráfico.
    • Pero eso sería mucho más difícil, supongo ...


Pero estoy bastante seguro de que esta idea podría usarse como punto de partida para algo mucho más interesante:

  • Acerca de las cosas que no se documentan: agregar nuevas etiquetas que serán reconocidas no debería ser demasiado difícil
    • Solo tienes que agregarlos a una lista al principio del filtro
  • Mejorar los docblocks existentes podría ser más difícil, tengo que admitir
  • Una cosa buena es que esto podría ser totalmente automatizado.
  • Usando Eclipse PDT, tal vez esto podría configurarse como una herramienta externa , por lo que al menos podemos iniciarlo desde nuestro IDE.