example - phpdocumentor download windows

Analizar comentarios de PHP Doc en una estructura de datos

Question

Estoy usando Reflection API en PHP para extraer una cadena DocComment (PHPDoc) de un método

$r = new ReflectionMethod($object);
$comment = $r->getDocComment();

Esto devolverá una cadena que se ve algo como esto (dependiendo de qué tan bien se documentó el método)

/**
* Does this great things
*
* @param string $thing
* @return Some_Great_Thing
*/

¿Hay algún método o función incorporada que pueda analizar una cadena de comentario de PHP en una estructura de datos?

$object = some_magic_function_or_method($comment_string);

echo ''Returns a: '', $object->return;

Al carecer de eso, ¿qué parte del código fuente de PHPDoc debería estar mirando? Hago esto yo mismo.

La falta y / o además de eso, ¿hay un código de un tercero que se considere "mejor" que el código PHPDoc?

Me doy cuenta de que analizar estas cadenas no es ciencia de cohetes, ni siquiera ciencia de la computación, pero preferiría una biblioteca / rutina / método bien probado que se haya diseñado para lidiar con gran parte del código de PHP Doc semi-no correcto que podría existir en la naturaleza.

Answer 1

Como se señaló en una de las respuestas anteriores, puede usar phpDocumentor. Si usa el compositor, simplemente agregue "phpdocumentor / reflection-docblock": "~ 2.0" a su bloque "require".

Ver esto para un ejemplo: https://github.com/abdulla16/decoupled-app/blob/master/composer.json

Para ver ejemplos de uso, consulte: https://github.com/abdulla16/decoupled-app/blob/master/Container/Container.php

Answer 2

Me sorprende que aún no se haya mencionado: ¿qué hay de usar Zend_Reflection de Zend Framework? Esto puede ser útil especialmente si trabaja con un software basado en Zend Framework como Magento.

Consulte el Manual de Zend Framework para algunos ejemplos de código y la documentación de API para conocer los métodos disponibles.

Hay maneras diferentes de hacer esto:

• Pase un nombre de archivo a Zend_Reflection_File.
• Pase un objeto a Zend_Reflection_Class.
• Pase un objeto y un nombre de método a Zend_Reflection_Method.
• Si realmente solo tiene la cadena de comentarios a la mano, incluso podría juntar el código para una pequeña clase ficticia, guardarlo en un archivo temporal y pasar ese archivo a Zend_Reflection_File.

Vayamos por el caso simple y supongamos que tiene una clase existente que desea inspeccionar.

El código sería así (no probado, por favor, perdóneme):

$method = new Zend_Reflection_Method($class, ''yourMethod'');
$docblock = $method->getDocBlock();

if ($docBlock->hasTag(''return'')) {
    $tagReturn = $docBlock->getTag(''return''); // $tagReturn is an instance of Zend_Reflection_Docblock_Tag_Return
    echo "Returns a: " . $tagReturn->getType() . "<br>";
    echo "Comment for return type: " . $tagReturn->getDescription();
}

Answer 3

Puede usar DocBlox ( http://github.com/mvriel/docblox ) para generar una estructura de datos XML para usted; puede instalar DocBlox usando PEAR y luego ejecutar el comando:

docblox parse -d [FOLDER] -t [TARGET_LOCATION]

Esto generará un archivo llamado structure.xml que contiene todos los metadatos sobre su código fuente, incluidos los docblocks analizados.

O

Puede usar las clases DocBlox_Reflection_DocBlock* para analizar directamente una parte del texto de DocBlock.

Esto puede hacerlo asegurándose de que tiene habilitada la carga automática (o incluya todos los archivos DocBlox_Reflection_DocBlock *) y ejecute lo siguiente:

$parsed = new DocBlox_Reflection_DocBlock($docblock);

Luego puede usar los getters para extraer la información que desee.

Nota: no necesita eliminar los asteriscos; la clase Reflection se ocupa de esto.

Answer 4

Puede utilizar la clase " DocBlockParser " del proyecto de código abierto Fabien Potencier Sami ("Otro generador de documentación API PHP").
Antes que nada, saca a Sami de GitHub .
Este es un ejemplo de cómo usarlo:

<?php

require_once ''Sami/Parser/DocBlockParser.php'';
require_once ''Sami/Parser/Node/DocBlockNode.php'';

class TestClass {
    /**
     * This is the short description.
     *  
     * This is the 1st line of the long description 
     * This is the 2nd line of the long description 
     * This is the 3rd line of the long description   
     *  
     * @param bool|string $foo sometimes a boolean, sometimes a string (or, could have just used "mixed")
     * @param bool|int $bar sometimes a boolean, sometimes an int (again, could have just used "mixed") 
     * @return string de-html_entitied string (no entities at all)
     */
    public function another_test($foo, $bar) {
        return strtr($foo,array_flip(get_html_translation_table(HTML_ENTITIES)));
    }
}

use Sami/Parser/DocBlockParser;
use Sami/Parser/Node/DocBlockNode;

try {
    $method = new ReflectionMethod(''TestClass'', ''another_test'');
    $comment = $method->getDocComment();
    if ($comment !== FALSE) {
        $dbp = new DocBlockParser();
        $doc = $dbp->parse($comment);
        echo "/n** getDesc:/n";
        print_r($doc->getDesc());
        echo "/n** getTags:/n";
        print_r($doc->getTags());
        echo "/n** getTag(''param''):/n";
        print_r($doc->getTag(''param''));
        echo "/n** getErrors:/n";
        print_r($doc->getErrors());
        echo "/n** getOtherTags:/n";
        print_r($doc->getOtherTags());
        echo "/n** getShortDesc:/n";
        print_r($doc->getShortDesc());
        echo "/n** getLongDesc:/n";
        print_r($doc->getLongDesc());
    }
} catch (Exception $e) {
    print_r($e);
}

?>

Y aquí está el resultado de la página de prueba:

** getDesc:
This is the short description.

This is the 1st line of the long description 
This is the 2nd line of the long description 
This is the 3rd line of the long description
** getTags:
Array
(
    [param] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [0] => Array
                                (
                                    [0] => bool
                                    [1] => 
                                )

                            [1] => Array
                                (
                                    [0] => string
                                    [1] => 
                                )

                        )

                    [1] => foo
                    [2] => sometimes a boolean, sometimes a string (or, could have just used "mixed")
                )

            [1] => Array
                (
                    [0] => Array
                        (
                            [0] => Array
                                (
                                    [0] => bool
                                    [1] => 
                                )

                            [1] => Array
                                (
                                    [0] => int
                                    [1] => 
                                )

                        )

                    [1] => bar
                    [2] => sometimes a boolean, sometimes an int (again, could have just used "mixed")
                )

        )

    [return] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [0] => Array
                                (
                                    [0] => string
                                    [1] => 
                                )

                        )

                    [1] => de-html_entitied string (no entities at all)
                )

        )

)

** getTag(''param''):
Array
(
    [0] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [0] => bool
                            [1] => 
                        )

                    [1] => Array
                        (
                            [0] => string
                            [1] => 
                        )

                )

            [1] => foo
            [2] => sometimes a boolean, sometimes a string (or, could have just used "mixed")
        )

    [1] => Array
        (
            [0] => Array
                (
                    [0] => Array
                        (
                            [0] => bool
                            [1] => 
                        )

                    [1] => Array
                        (
                            [0] => int
                            [1] => 
                        )

                )

            [1] => bar
            [2] => sometimes a boolean, sometimes an int (again, could have just used "mixed")
        )

)

** getErrors:
Array
(
)

** getOtherTags:
Array
(
)

** getShortDesc:
This is the short description.
** getLongDesc:
This is the 1st line of the long description 
This is the 2nd line of the long description 
This is the 3rd line of the long description

Answer 5

Revisa

http://pecl.php.net/package/docblock

La función docblock_tokenize () te llevará a un punto intermedio allí, creo.

Answer 6

Según su descripción, solo puedo sospechar lo que está tratando de hacer (documentación del código PHP). Como no dices por qué intentas hacer esto, solo puedo especular.

Tal vez deberías probar otro enfoque. Para documentar el código PHP (si eso es lo que estás intentando) utilizaría Doxygen y, a juzgar por el comentario del código, ya está formateado para doxygen.

Con Graphviz , Doxygen también renderiza buenos diagramas de clases y árboles de llamadas.

Answer 7

Si intenta leer las etiquetas @ y sus valores, usar preg_match sería la mejor solución.

Answer 8

Siempre puedes ver la fuente desde phpDoc . El código está bajo LGPL por lo que si decides copiarlo necesitarás licenciar tu software con la misma licencia Y agregar correctamente los avisos correctos.

EDITAR: A menos que, como @Samuel Herzog, señaló que lo usa como una biblioteca.

Gracias @Samuel Herzog por la aclaración.

Answer 9

Sugiero un apéndice, es bastante genial y está bien vivo y se usa en muchos frameworks php5 ...

http://code.google.com/p/addendum/

Verifique las pruebas para ver ejemplos

http://code.google.com/p/addendum/source/browse/trunk#trunk%2Fannotations%2Ftests

Answer 10

Te sugiero que eches un vistazo a http://code.google.com/p/php-annotations/

El código es bastante simple para ser modificado / entendido si es necesario.

Answer 11

Versión actualizada del código de user1419445. El DocBlockParser::parse() se cambia y necesita un segundo parámetro de contexto. También parece estar ligeramente acoplado con phpDocumentor, por lo que, en aras de la simplicidad, supongo que tienes instalado Sami a través de Composer. El siguiente código funciona para Sami v4.0.16

<?php

require_once ''vendor/autoload.php'';

class TestClass {
    /**
     * This is the short description.
     *  
     * This is the 1st line of the long description 
     * This is the 2nd line of the long description 
     * This is the 3rd line of the long description   
     *  
     * @param bool|string $foo sometimes a boolean, sometimes a string (or, could have just used "mixed")
     * @param bool|int $bar sometimes a boolean, sometimes an int (again, could have just used "mixed") 
     * @return string de-html_entitied string (no entities at all)
     */
    public function another_test($foo, $bar) {
        return strtr($foo,array_flip(get_html_translation_table(HTML_ENTITIES)));
    }
}

use Sami/Parser/DocBlockParser;
use Sami/Parser/Filter/PublicFilter;
use Sami/Parser/ParserContext;

try {
    $method = new ReflectionMethod(''TestClass'', ''another_test'');
    $comment = $method->getDocComment();
    if ($comment !== FALSE) {
        $dbp = new DocBlockParser();
        $filter = new PublicFilter;
        $context = new ParserContext($filter, $dbp, NULL);
        $doc = $dbp->parse($comment, $context);
        echo "/n** getDesc:/n";
        print_r($doc->getDesc());
        echo "/n** getTags:/n";
        print_r($doc->getTags());
        echo "/n** getTag(''param''):/n";
        print_r($doc->getTag(''param''));
        echo "/n** getErrors:/n";
        print_r($doc->getErrors());
        echo "/n** getOtherTags:/n";
        print_r($doc->getOtherTags());
        echo "/n** getShortDesc:/n";
        print_r($doc->getShortDesc());
        echo "/n** getLongDesc:/n";
        print_r($doc->getLongDesc());
    }
} catch (Exception $e) {
    print_r($e);
}

?>