Double Include Prevention Code in PHP Prevents Doxygen From Generating Documentation

Question

I am writing relatively complex PHP applications and have several files for class definitions formatted as follows:

<?php

if(!class_exists("FooBar"))
{

/**
 * This is documentation for the class FooBar
 */
class FooBar
{
    /**
     * Documentation for FooBar's constructor
     */
    public function __construct() {
        ;
    }
}

} // class_exists

This is to prevent multiple definition errors with complex class hierarchies and applications.

However, Doxygen does not document any classes that are specified this way. Commenting out or removing the if(!class_exists()) statement causes Doxygen to correctly document this class, but introduces errors with applications.

Is there any way I can force Doxygen to generate documentation for these classes?

This is not an answer, this might be subject to discussion, and ofcourse I do not know how your class hierarchies are build up, but it seems to me that using namespaces is would be a better approach to prevent multiple definition errors... — giorgio
– giorgio, Commented Jun 30, 2014 at 8:20
Well, defining classes conditionally (inside if blocks) is a really, really bad idea. If you have a large/complex code base then you should be using namespaces to organize your code. In other words, you should not be trying to somehow force Doxygen to handle bad practices; you should not be using bad practices to begin with. — Sverri M. Olsen
– Sverri M. Olsen, Commented Jun 30, 2014 at 8:22
Namespaces do not solve double includes for even very simple class hierarchies, otherwise I would have used them. If I have base class A, and sub-classes B and C, then use both B and C in my application, the effect is an include statement for class A is being called twice resulting in a double definition error. — Marcus Harrison
– Marcus Harrison, Commented Jun 30, 2014 at 8:26
@MarcusHarrison Well, if you define a class in a file then it should never be included more than once, anyway. Hiding poorly written code does not make it okay. — Sverri M. Olsen
– Sverri M. Olsen, Commented Jun 30, 2014 at 8:30
@MarcusHarrison Ah. Autoloading would fix this problem. This article explains it quite nicely. — Sverri M. Olsen
– Sverri M. Olsen, Commented Jun 30, 2014 at 8:39

albert · Accepted Answer · 2019-01-27 14:42:16Z

As mentioned by @Sverri in the comments, I also think that autoloading is a good way to solve your problem (what it already did, as it seems).

But just for the case you (or someone else) is looking for a doxygen-only solution:

You can use INPUT_FILTERS in doxygen to remove or change some parts of the source code before creating the documentation.

You can use the following php code to remove all lines containing if(!class_exists and the braces { } that belong to this if-block, as long as it is not followed by another block.

// input
$source = file_get_contents($argv[1]);

// removes the whole line
list($head,$tail) = preg_split('/.*if\(!class_exists\(.+/', $source, 2);   

$openingBracePos = strpos($tail,'{');
$closingBracePos = strrpos($tail,'}');

if($openingBracePos !== false && $closingBracePos !== false)
    $source = $head . substr($tail,$openingBracePos+1,
                             $closingBracePos-$openingBracePos-1);

echo $source;

This filter truns

<?php

if(!class_exists("FooBar"))     // This comment will also disappear
{

/**
 * This is documentation for the class FooBar
 */
class FooBar
{
    /**
     * Documentation for FooBar\'s constructor
     */
    public function __construct() {
        ;
    }
}

} // class_exists

into

<?php



/**
 * This is documentation for the class FooBar
 */
class FooBar
{
    /**
     * Documentation for FooBar's constructor
     */
    public function __construct() {
        ;
    }
}

Note: On windows I have to call the filter like this: C:\xampp\php\php.exe php_var_filter.php

You can find some more input filters to improve doxygen's php support on GitHub.

Collectives™ on Stack Overflow

Double Include Prevention Code in PHP Prevents Doxygen From Generating Documentation

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related