Doxygen strange problem while documenting PHP if

Question

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: No $action2

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.

if in code

Doxygen converts it to this Wrong listing of variables

@yes123 I believe it generates documentation from PHP comments. — alex
– alex, Commented May 31, 2011 at 0:51
Since all 3 solutions (by now) are valid and each of them provide very useful information, I had to give 3 vote ups, and an check mark for David, which was first and also point additional link, which will be very helpful for someone if decide to start using doxygen. — RRStoyanov
– RRStoyanov, Commented Jun 2, 2011 at 7:14

David · Accepted Answer · 2018-12-25 17:17:31Z

5

+150

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.

edited Dec 25, 2018 at 17:17

answered Jun 2, 2011 at 1:27

David

18.4k10 gold badges74 silver badges100 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Bill B · Accepted Answer · 2011-06-02 01:34:20Z

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.

answered Jun 2, 2011 at 1:34

Bill B

1,30013 silver badges17 bronze badges

1 Comment

RRStoyanov Over a year ago

Thank for your reply. I think (1) is good solution, now when you point to that, I check the documentation of doxygen at (stack.nl/~dimitri/doxygen/autolink.html) and I saw that even they use ; in the end. Nice cache! About (2) I started with phpdoc, but after that I switch to doxygen because of the flexibility - especially adding the custom aliases and also using their GUI makes things a bit easy too. I loved phpdoc, but it's without support from long time (nor that doxygen is with some constat). Anyway I mostly like will use your suggestions. Thanks!

albert · Accepted Answer · 2018-12-22 12:15:38Z

1

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?

edited Dec 22, 2018 at 12:15

albert

9,2103 gold badges24 silver badges42 bronze badges

answered Jun 2, 2011 at 1:28

GmonC

11k1 gold badge33 silver badges39 bronze badges

1 Comment

RRStoyanov Over a year ago

Thanks, that seems to fix partly the problem. The code is entirely mine, so I can fix whatever is needed. Thanks!

Collectives™ on Stack Overflow

Doxygen strange problem while documenting PHP if

3 Answers 3

Comments

1 Comment

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

Comments

1 Comment

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related