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

Answer 1

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.

Answer 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.