Doxygen странная проблема при документировании PHP, если - PullRequest
Новая
       2

Doxygen странная проблема при документировании PHP, если

9 голосов
/ 31 мая 2011

Я сталкиваюсь со странной проблемой, когда пытаюсь задокументировать свой проект. У меня есть следующий код: 

//! Set default ::$action for called controller. If no action is called, default (index) will be set.
$action = isset($_GET[ 'action']) ? $_GET[ 'action'] : 'index';

if ($action) {
    echo 'something 1';
}else{
    echo 'something 2';
}

//! Set default ::$action2 for called controller. If no action is called, default (index) will be set.
$action2 = isset($_GET[ 'action']) ? $_GET[ 'action'] : 'index';

//! Set default ::$action3 for called controller. If no action is called, default (index) will be set.
$action3 = isset($_GET[ 'action']) ? $_GET[ 'action'] : 'index';

Doxygen генерирует следующее: No $action2

Как видите, $ action2 отсутствует. Я проверил один из моих других файлов и увидел ту же проблему. Следующая вещь после if оператора никогда не документируется, но следующая после этого документируется. Если я удаляю оператор if из приведенного выше примера, я получаю документацию для всех 4 переменных - $page, $action, action2 и action3.

Я трачу огромное время, пытаясь понять, что именно не так, но не повезло, поэтому каждое предложение приветствуется.

Система: Windows XP x64 с Doxygen 1.7.4. (Я использую Doxygen GUI)

UPDATE Кроме того, когда у меня есть что-то подобное в моем коде (обратите внимание на пропущенный else для оператора if). Когда я добавляю }else{}, все работает. Далее $variables снова не задокументировано, но это обновление было о if/else.

if in code

Doxygen преобразует его в это Wrong listing of variables

Ответы [ 3 ]

5 голосов
/ 02 июня 2011

Проверьте это http://www.doxygen.nl/manual/autolink.html, которое объясняет странность, которую вы видите с первым фрагментом кода.

К сожалению, Doxygen не очень хорошо документирует процедурный код PHP И, проверив всю собственную документацию, сгенерированную Doxygen, я не могу найти никаких документированных переменных для какой-либо функции или метода, если они не определены свойствами класса.

В остальном, я думаю, что крупнейшим дружественным к PHP Doxygen проектом является Drupal, их рекомендации были написаны для того, чтобы максимально полно использовать систему обработки комментариев Doxygen. http://drupal.org/node/1354

Обратите внимание: если это не тот ответ, который вы ищете, или я полностью не в курсе, пожалуйста, немедленно сообщите мне, чтобы я мог удалить этот ответ.

2 голосов
/ 02 июня 2011

Я считаю, что это ошибка в doxygen при разборе php.В 2008 году была аналогичная проблема, над которой работали, но так и не решили - https://bugzilla.gnome.org/show_bug.cgi?id=528815

Я готов поспорить, что ваша проблема связана.

У меня есть пара предложений:

1) Возможно, я наткнулся на обходной путь.Добавление точки с запятой после того, как блок, кажется, заставляет его вести себя правильно. 

if ($action) {
  echo 'something 1';
}else{
  echo 'something 2';
};

Однако я не знаю, вызовет ли это другие проблемы с анализом doxygen.

2) Я использую doxygenдля моих проектов на c ++, но я использую phpdoc для своих проектов php, потому что у меня были лучшие результаты с ним.Вы можете сделать то же самое, если вы не привязаны к doxygen по политическим или практическим причинам.

1 голос
/ 02 июня 2011

Только PHP: Doxygen требует, чтобы все операторы PHP (то есть код) были обернуты в функции / методы, иначе вы можете столкнуться с проблемами разбора. Source

Используете ли вы php-фреймворк с открытым исходным кодом?Можно ли обернуть ваш код в функции / методы, где это необходимо?

...