Doxygen and PHP - how to parse code that is not run?

Question

I have some PHP code that is documented with Doxygen. In this code, there are a number of hooks, which are functions that my code calls, but the functions themselves are defined by the users of this code.

I want to document the hooks, but because the functions don't exist in my code (the users define the functions, my code just calls them) there is nowhere for me to attach the Doxygen comments to - unless I define a fake function.

Is there some way I can avoid defining this fake function? If I were using C I could define the function but use #ifdefs to hide it from the compiler (but still have Doxygen see it), but I'm not sure what the equivalent is in PHP. Ideally I'd want something that wouldn't result in any additional effort on the part of the PHP parser.

Any suggestions? This is what I am trying to document, and how I have it now with the fake function:

/// This is an example hook.
/**
 * Register it with $hooks['example'][] = 'your_function_name_here';
 *
 * @param string $dummy
 *   Dummy parameter.
 */
function hook_example($dummy) { };  // fake function for Doxygen

linepogl · Accepted Answer · 2012-02-16 10:18:04Z

2

If you want other programmers to implement your hooks use OOP interfaces and abstract classes. This will sanitize your code.

As a side effect, Doxygen will be very happy to document the abstract methods.

answered Feb 16, 2012 at 10:18

linepogl

9,3854 gold badges36 silver badges45 bronze badges

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

1 Comment

Malvineous Over a year ago

Thanks for the suggestion, but abstract classes are overkill in this situation. The hooks are typically a couple of lines of code with no shared data, so declaring a class and having functions to register/unregister them would cause too much bloat. These hooks are supposed to be quick and simple to implement.

Malvineous · Accepted Answer · 2012-02-17 00:56:40Z

2

Since PHP doesn't support #ifdef blocks, I think the only way this can be done is to take the comments and fake function declarations and put them in another .php file. Configure Doxygen to include this new file, but don't include() it anywhere in the rest of the code.

Then the fake functions will appear in the documentation, but the PHP parser will never know about them.

answered Feb 17, 2012 at 0:56

Malvineous

27.7k19 gold badges129 silver badges161 bronze badges

Collectives™ on Stack Overflow

Doxygen and PHP - how to parse code that is not run?

2 Answers 2

1 Comment

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Related