Doxygen 正在使用 php __construct() 跳过文件

Question

我正在使用 codeigniter 框架开发一个网站。为了记录它，我安装了 doxygen。当 doxygen 遇到具有以下结构的文件时，会发生一些奇怪的事情：

<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
/**
 * @class
 * @brief The class brief 
 */
  class Catalogo extends CI_Controller {    
    public function __construct(){         
        parent::__construct();
        $this->load->model('catalogomodel');
        $this->load->library('img');
   }
    public function foo(){
       ..some code..
    }
/* End of file catalogo.php */
/* Location: ./application/controllers/catalogo.php */

这是唯一被跳过的文件，其他在 codeigniter 中具有通常结构的文件按应有的方式记录。

<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
/**
 * @class
 * @brief The class brief 
 */
  class Catalogo extends CI_Controller {
    public function index(){
      ...some code to load models, libraries and views ...
    }
   /* End of file catalogo.php */
   /* Location: ./application/controllers/catalogo.php */

Answer 1

我不确定您提供的示例与您的实际应用程序有多接近，但对于上面的原始示例代码：

您的类声明似乎没有关闭（缺少}）。这将阻止 doxygen 解析类声明，并将被跳过。添加结束 } 允许 doxygen 完全解析类，并且它应该包含在文档中，但是不会出现该类或其成员函数的文档，并且 __construct 不会被列为成员函数。

进行此更改后，Doxygen 1.8.0 在处理内容时会报告两个警告：

catalogo.php:6: warning: Compound Catalogo is not documented.
catalogo.php:13: warning: Member foo() (function) of class Catalogo is not documented.

第一个与空的@class 标记有关。 Doxygen 期望@class 后面紧跟注释适用的类名，并且通常在 doxygen 不在它所描述的构造旁边时使用。在这种情况下，@class 可以被删除，因为Catalogo 类声明紧跟在它之后。或者，您也可以明确指定@class Catalogo。进行此更改将使第一个警告静音，并导致 Catalogo 的文档出现在 doxygen 输出中，但 __construct 仍将不存在，foo 将不会链接到详细说明。

要解决第二个警告，您需要提供foo 的文档，例如：

/**
 * Documentation for foo.
 */
public function foo(){
}

此更改将导致foo 出现在文档中，并带有指向其详细说明的链接。 __construct 仍将不存在，但为它添加类似的文档：

/**
 * Documentation for __construct.
 */
public function __construct() {         
}

使这两个函数都出现，并带有指向其详细描述的链接。这一切都假定默认的 doxygen 配置 (doxygen -g) 和 Doxygen 1.8.0。我测试的最终代码（看起来运行良好）是：

<?php if ( ! defined('BASEPATH')) exit('No direct script access allowed');
/**
 * @brief The class brief 
 */
class Catalogo extends CI_Controller {
    /**
     * Documentation for __construct.
     */
    public function __construct(){         
        parent::__construct();
        $this->load->model('catalogomodel');
        $this->load->library('img');
    }

    /**
     * Documentation for foo.
     */
    public function foo(){
        ..some code..
    }
}
/* End of file catalogo.php */
/* Location: ./application/controllers/catalogo.php */