Doxygen strange problem while documenting PHP if

问题:

I face a strange problem while I'm trying to document a project of mine. I have the following code:

//! 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 generates the following:

As you may see, $action2 is missing. I check one of my other files and saw same problem. Next thing after if statement is never documented, but the one after that is documented. If I remove the if statement from above example, I get documentation for all 4 variables - $page, $action, action2 and action3.

I spend enormous time of trying to understand what exactly is wrong, but no luck, so every suggestion is welcomed.

System is: Windows XP x64 with Doxygen 1.7.4. (I'm using the Doxygen GUI)

UPDATE Also, when I have something like that in my code (notice the missing else for the if statement). When I add the }else{} however it works. Next $variables is not documented again, but that update was about the if/else.

Doxygen converts it to this

回答1:

Check out this http://www.doxygen.nl/manual/autolink.html which explains the weirdness you're seeing with the first code snippet.

Unfortunately Doxygen doesn't do so well documenting procedural PHP code AND after checking all of my own doxygen generated documentation, I can't find any documented variables for any function or method unless they are defined class properties.

Otherwise, I think the largest PHP Doxygen friendly project out there is Drupal, their guidelines were written to use Doxygen's comment processing system to it's fullest. http://drupal.org/node/1354

Note, if this is not the answer you're looking for and or I'm completely off target, please let me know immediately so I can delete this answer.

回答2:

I believe it's a bug in doxygen when parsing php. There was a similar issue from 2008 that was worked on but never resolved - https://bugzilla.gnome.org/show_bug.cgi?id=528815

I'm willing to bet that your issue is related.

I have a couple of suggestions:

1) I may have stumbled onto a workaround. Adding a semicolon after the block seems to make it behave correctly.

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

However, I don't know if this will cause other issues with doxygen's parsing.

2) I use doxygen for my c++ projects, but I use phpdoc for my php projects because I have had better results with it. You might consider doing the same if you're not tied to doxygen for political or practical reasons.

回答3:

PHP only: Doxygen requires that all PHP statements (i.e. code) is wrapped in a functions/methods, otherwise you may run into parse problems. Source

Are you using an open source php framework? Is it possible to wrap your code into functions/methods where needed?