Анализ комментариев PHP Doc в структуру данных

Я использую Reflection API в PHP, чтобы вытащить строку DocComment (PHPDoc) из метода

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

Это вернет строку, которая выглядит примерно так (в зависимости от того, насколько хорошо документирован метод)

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

Есть ли встроенные методы или функции, которые могут анализировать строку комментариев PHP Doc Comment в структуру данных?

$object = some_magic_function_or_method($comment_string);

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

Если этого не делать, то какую часть исходного кода PHPDoc я должен смотреть на это самостоятельно.

Отсутствие и/или дополнение к этому, есть ли сторонний код, который считается "лучше" при этом, что код PHPDoc?

Я понимаю, что синтаксический анализ этих строк - это не наука о ракетах или даже компьютерная наука, но я бы предпочел хорошо протестированную библиотеку/рутину/метод, который был построен для обработки большого количества janky, полунеправильного PHP Doc-код, который может существовать в дикой природе.

Ответ 1

Я удивлен, что это еще не упоминалось: как насчет использования Zend_Reflection Zend Framework? Это может пригодиться, особенно если вы работаете с программным обеспечением, основанным на Zend Framework, например Magento.

См. Руководство по Zend Framework для некоторых примеров кода и Документация API для доступных методов.

Существуют разные способы сделать это:

Передайте имя файла Zend_Reflection_File.
Передайте объект Zend_Reflection_Class.
Передайте объект и имя метода в Zend_Reflection_Method.
Если у вас действительно есть только строка комментариев, вы даже можете скомпоновать код для небольшого класса фиктивного типа, сохраните его во временном файле и передайте этот файл Zend_Reflection_File.

Отпустим простой случай и предположим, что у вас есть существующий класс, который вы хотите проверить.

Код будет таким (непроверенный, пожалуйста, простите меня):

$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();
}

Ответ 2

Вы можете использовать класс DocBlockParser из Fabien Potencier Сами ( "Еще один генератор документации API PHP" ) с открытым исходным кодом.
Прежде всего, получите саами от GitHub.
Это пример того, как его использовать:

<?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);
}

?>

И вот результат тестовой страницы:

Ответ 3

Вы можете использовать DocBlox (http://github.com/mvriel/docblox) для создания структуры данных XML для вас; вы можете установить DocBlox, используя PEAR, а затем запустите команду:

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

Это создаст файл с именем structure.xml, который содержит все метаданные о вашем исходном коде, включая проанализированные docблоки.

ИЛИ

Вы можете использовать классы DocBlox_Reflection_DocBlock * для прямого анализа фрагмента текста DocBlock.

Это можно сделать, если вы включили автозагрузку (или включили все файлы DocBlox_Reflection_DocBlock *) и выполните следующие действия:

$parsed = new DocBlox_Reflection_DocBlock($docblock);

Затем вы можете использовать getters для извлечения необходимой информации.

Примечание: вам не нужно удалять звездочки; класс Reflection позаботится об этом.

Ответ 4

Отъезд

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

Функция docblock_tokenize(), как мне кажется, поможет вам в этом плане.

Ответ 5

Я предлагаю добавление, его довольно здорово и хорошо жив и используется во многих фреймворках php5...

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

Проверьте примеры тестов

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

Ответ 6

Вы всегда можете просмотреть источник из phpDoc. Код находится под LGPL, поэтому, если вы решите его скопировать, вам нужно будет лицензировать свое программное обеспечение под одной лицензией и правильно добавить правильную уведомления.

EDIT: Если, как @Samuel Herzog, если вы используете его как библиотеку.

Спасибо @Samuel Herzog за разъяснения.

Ответ 7

Из вашего описания я могу только подозревать, что вы пытаетесь сделать (документация на PHP-код). Поскольку вы не указываете, почему вы пытаетесь это сделать, я могу только предполагать.

Возможно, вам стоит попробовать другой подход. Чтобы документировать PHP-код (если это то, что вы пытаетесь), я бы использовал Doxygen и из внешнего вида вашего комментария кода, он уже отформатирован для doxygen.

С Graphviz, Doxygen также визуализирует диаграммы классов и деревья вызовов.

Ответ 8

Если вы пытаетесь прочитать в тегах @и их значениях, то наилучшим решением будет использование preg_match.

Ответ 9

Я предлагаю вам взглянуть на http://code.google.com/p/php-annotations/

Код достаточно прост для изменения/понимания при необходимости.

Ответ 10

Как указано в одном из приведенных выше ответов, вы можете использовать phpDocumentor. Если вы используете композитор, просто добавьте "phpdocumentor/reflection-docblock": "~ 2.0" на ваш блок "требовать".

Посмотрите это на примере: https://github.com/abdulla16/decoupled-app/blob/master/composer.json

Примеры использования см. в: https://github.com/abdulla16/decoupled-app/blob/master/Container/Container.php