php - 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 */