Doxygen: как описать переменные члена класса в php?

Question

Я пытаюсь использовать doxygen для разбора php-кода в выводе xml. Doxygen не разбирает описание переменных членов класса.

Вот мой пример php-файла:

<?php
class A
{
    /**
      * Id on page.
      *
      * @var integer
      */
    var $id = 1;
}
?>

Обратите внимание, что комментарий имеет краткое описание и тип переменной. Вот XML, я получил из этого источника:

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xsi:noNamespaceSchemaLocation="compound.xsd" version="1.7.2">
  <compounddef id="class_a" kind="class" prot="public">
<compoundname>A</compoundname>
  <sectiondef kind="public-attrib">
  <memberdef kind="variable" id="class_a_1ae97941710d863131c700f069b109991e" prot="public" static="no" mutable="no">
    <type></type>
    <definition>$id</definition>
    <argsstring></argsstring>
    <name>$id</name>
    <initializer> 1</initializer>
    <briefdescription>
    </briefdescription>
    <detaileddescription>
    </detaileddescription>
    <inbodydescription>
    </inbodydescription>
    <location file="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" line="11" bodyfile="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" bodystart="11" bodyend="-1"/>
  </memberdef>
  </sectiondef>
<briefdescription>
</briefdescription>
<detaileddescription>
</detaileddescription>
<location file="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" line="5" bodyfile="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" bodystart="4" bodyend="12"/>
<listofallmembers>
  <member refid="class_a_1ae97941710d863131c700f069b109991e" prot="public" virt="non-virtual"><scope>A</scope><name>$id</name></member>
</listofallmembers>
  </compounddef>
</doxygen>

Ни описание, ни тип не были проанализированы. Как я могу это исправить?

Answer 1

Я использую входной фильтр для вставки шрифтов из аннотации @var, встроенной в объявление переменной, и удаляю аннотацию @var, так как она имеет другое значение в Doxygen. Для получения дополнительной информации см. Ошибку # 626105.

Поскольку Doxygen использует C-подобный парсер, при запуске входного фильтра он может распознавать типы.

<?php
$source = file_get_contents($argv[1]);

$regexp = '#\@var\s+([^\s]+)([^/]+)/\s+(var|public|protected|private)\s+(\$[^\s;=]+)#';
$replac = '${2} */ ${3} ${1} ${4}';
$source = preg_replace($regexp, $replac, $source);

echo $source;

Это быстрый взлом, и, возможно, есть ошибки, он просто работает для моего кода:

Вы можете включить фильтр ввода с опцией INPUT_FILTER в вашем Doxyfile. Сохраните приведенный выше код в файл с именем php_var_filter.php и установите значение фильтра "php php_var_filter.php".

Answer 2

У меня была та же проблема, поэтому я создал простой фильтр ввода, который поворачивает основной синтаксис

/**
 * @var int
 */
public $id;

в

/**
 * @var int $id
 */
public $id;

что было бы в любом случае излишним. Таким образом, Eclipse IDE может использовать тот же самый блок документов, что и Doxygen.

Вы можете скачать входной фильтр здесь:

https://bitbucket.org/tamasimrei/misc-tools/src/master/doxygen/filter.php

См. Руководство по Doxygen о том, как использовать входной фильтр.

Инструмент также избегает обратной косой черты в docblocks, так что вы можете использовать пространства имен там.

Answer 3

Блок будет правильно связан, если вы пропустите @var. Это никуда не дает объявить тип, что раздражает, но, по крайней мере, описание будет работать.

Тестовая версия: Doxygen 1.7.1

Answer 4

Хотя это не является прямым ответом на ваш вопрос: если вы можете использовать правильный инструмент для работы, взгляните на DocBlox. Он также генерирует XML-документ для дальнейшего преобразования в HTML или любой другой формат отображения и очень хорошо работает для PHP. Это не нарушит вашего обычного использования docblock.

В качестве примера вывода ознакомьтесь с документацией по Zend Framework API.

Answer 5

Кажется, это ошибка в Doxygen. У меня та же проблема с документацией в HTML.

В настоящее время работает:

class A
{
    var $id = 1; /**< Id on page. */
}

Но эти комментарии не распознаются средой IDE NetBeans как документация для данной области.

Answer 6

Большое спасибо Горану за его кислородный фильтр! Немного расширив ту же идею, чтобы сделать надлежащую документацию по параметрам функции:

Включите типы массивов объектов @param в стиле Zend Studio в документацию doxygen:

// Change the following:
// /** @param VarType[] $pParamName Description **/
// function name(array $pParamName) {

// Into:
// /** @param array $pParamName Description **/
// function name(VarType[] $pParamName) {
$regexp = '#\@param\s+([^\s]+)\[\]\s+(\$[^\s]+)\s+([^/]+)/\s+(public|protected|private)?\s+function\s+([^\s]+)\s*\(([^)]*)array\s+\2([^)]*)\)(\s+){#s';
$replac = '@param array ${2} ${3}/ ${4} function ${5} (${6} ${1}[] ${2}${7})${8}{';
$lSource = preg_replace($regexp, $replac, $lSource);

Включите типы int/float/double/string @param в документацию doxygen:

// Change the following:
// /** @param (int|float|double|string) $pParamName Description **/
// function name($pParamName) {

// Into:
// /** @param (int|float|double|string) $pParamName Description **/
// function name((int|float|double|string) $pParamName) {
$regexp = '#\@param\s+(int|float|double|string)\s+(\$[^\s]+)\s+([^/]+)/\s+(public|protected|private)?\s+function\s+([^\(\s]+)\s*([^)]*)(\(|,)\s*\2([^)]*)\)(\s+){#s';

$replac = '@param ${1} ${2} ${3}/ ${4} function ${5}${6}${7}${1} ${2}${8})${9}{ '; //${6}${1} ${2}${7})${8}{';
$lSource = preg_replace($regexp, $replac, $lSource);

Оба приведенных выше регулярных выражения также естественным образом работают с функциями, принимающими более одного аргумента. Также просто быстрый взлом, который работает для нашего кода, надеюсь, он поможет кому-то еще.

Answer 7

Для пользователей Windows без установленного php может быть полезно использовать скомпилированный в исполняемый файл php_var_filter.php скрипт кислородного фильтра из ответа