Question

I’m developing a web site using codeigniter framework. To document it, I’ve installed doxygen. Something weird is happening when doxygen meets files with the following structure:

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

This is the only files that are been skipped, other files with the usual structure in codeigniter are documented as they should.

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

I’m not sure how closely the examples you provided match your actual application, but for the original example code above:

Your class declarations do not appear to be closed (missing }). This will prevent doxygen from parsing the class declaration, and it will be skipped. Adding the closing } allows doxygen to fully parse the class, and it should be included in the documentation, however no documentation will appear for the class or its member functions, and __construct will not be listed as a member function.

Once this change is made, Doxygen 1.8.0 reports two warnings while processing the contents:

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

The first is related to the empty @class markup. Doxygen expects @class to be immediately followed by the class name that the comment applies to, and is typically used when the doxygen is not located next to the construct it describes. In this case, @class can be removed since the Catalogo class declaration immediately follows it. Alternatively, you can also specify @class Catalogo explicitly. Making this change will silence the first warning, and will cause the documentation for Catalogo to appear in the doxygen output, however __construct will still be absent and foo will not be linked to a detailed description.

To address the second warning, you’ll need to provide documentation for foo, something like:

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

This change will cause foo to appear in the documentation with a link to its detailed description. __construct will still not be present, however adding similar documentation for it:

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

causes both functions to appear with links to their detailed descriptions. This all assumes a default doxygen configuration (doxygen -g) and Doxygen 1.8.0. The final code I tested (and which appears to work fine) was:

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