PHP 中的双重包含预防代码可防止 Doxygen 生成文档答案

【问题标题】：Double Include Prevention Code in PHP Prevents Doxygen From Generating DocumentationPHP 中的双重包含预防代码可防止 Doxygen 生成文档
【发布时间】：2014-08-20 13:23:34
【问题描述】：

我正在编写相对复杂的 PHP 应用程序，并且有几个用于类定义的文件，格式如下：

<?php

if(!class_exists("FooBar"))
{

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

} // class_exists

这是为了防止复杂的类层次结构和应用程序出现多个定义错误。

但是，Doxygen 没有记录任何以这种方式指定的类。注释掉或删除 if(!class_exists()) 语句会导致 Doxygen 正确记录此类，但会在应用程序中引入错误。

有什么方法可以强制 Doxygen 为这些类生成文档？

【问题讨论】：

这不是一个答案，这可能需要讨论，当然我不知道你的类层次结构是如何建立的，但在我看来，使用命名空间是一种更好的方法防止多个定义错误...
好吧，有条件地定义类（在if 块内）是一个非常非常非常的坏主意。如果您有一个大型/复杂的代码库，那么您应该使用namespaces 来组织您的代码。换句话说，您不应该试图以某种方式强迫 Doxygen 处理不良做法。你不应该一开始就使用不好的做法。
命名空间不能解决即使是非常简单的类层次结构的双重包含，否则我会使用它们。如果我有基类 A，子类 B 和 C，然后在我的应用程序中同时使用 B 和 C，结果是类 A 的包含语句被调用两次，导致双重定义错误。
@MarcusHarrison 好吧，如果你在一个文件中定义一个类，那么无论如何它不应该被包含超过一次。隐藏写得不好的代码并不能解决问题。
@MarcusHarrison 啊。自动加载可以解决这个问题。 This article 解释得很好。

标签： php doxygen

【解决方案1】：

正如@Sverri 在 cmets 中提到的那样，我也认为自动加载是解决您的问题的好方法（它似乎已经做了）。

但仅针对您（或其他人）正在寻找仅 doxygen 解决方案的情况：

您可以在 doxygen 中使用INPUT_FILTERS 在创建文档之前删除或更改源代码的某些部分。

您可以使用以下 php 代码删除属于此 if-block 的所有包含 if(!class_exists 和大括号 { } 的行，只要它后面没有另一个块。

// 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;

这个过滤器运行

<?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

进入

<?php



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

注意：在 Windows 上，我必须像这样调用过滤器：C:\xampp\php\php.exe php_var_filter.php

您可以在GitHub 上找到更多输入过滤器来改进 doxygen 的 php 支持。

【讨论】：