Doxygen: how to describe class member variables in php?

Question

I'm trying to use doxygen to parse php code into xml output. Doxygen does not parse description of class member variables.

Here is my sample php file:

<?php
class A
{
    /**
      * Id on page.
      *
      * @var integer
      */
    var $id = 1;
}
?>

Note that comment has a brief description and variable type. Here is xml i got from this source:

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"    xsi:noNamespaceSchemaLocation="compound.xsd" version="1.7.2">
  <compounddef id="class_a" kind="class" prot="public">
<compoundname>A</compoundname>
  <sectiondef kind="public-attrib">
  <memberdef kind="variable" id="class_a_1ae97941710d863131c700f069b109991e" prot="public" static="no" mutable="no">
    <type></type>
    <definition>$id</definition>
    <argsstring></argsstring>
    <name>$id</name>
    <initializer> 1</initializer>
    <briefdescription>
    </briefdescription>
    <detaileddescription>
    </detaileddescription>
    <inbodydescription>
    </inbodydescription>
    <location file="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" line="11" bodyfile="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" bodystart="11" bodyend="-1"/>
  </memberdef>
  </sectiondef>
<briefdescription>
</briefdescription>
<detaileddescription>
</detaileddescription>
<location file="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" line="5" bodyfile="C:/projects/version6-7/asprunner/PHP/source/classes/a.php" bodystart="4" bodyend="12"/>
<listofallmembers>
  <member refid="class_a_1ae97941710d863131c700f069b109991e" prot="public" virt="non-virtual"><scope>A</scope><name>$id</name></member>
</listofallmembers>
  </compounddef>
</doxygen>

Neither description or type were parsed. How can I fix this?

Answer 1

I am using an input filter to insert typehints from the @var annotation inline with variable declaration, and remove the @var annotation as it has different meaning in Doxygen. For more info, see bug #626105.

As Doxygen uses C-like parser, when the input filter is run it can recognize types.

<?php
$source = file_get_contents($argv[1]);

$regexp = '#\@var\s+([^\s]+)([^/]+)/\s+(var|public|protected|private)\s+(\$[^\s;=]+)#';
$replac = '${2} */ ${3} ${1} ${4}';
$source = preg_replace($regexp, $replac, $source);

echo $source;

This is a quick hack, and probably have bugs, it just works for my code:

You can enable input filter with INPUT_FILTER option in your Doxyfile. Save the code above to file named php_var_filter.php and set the filter value to "php php_var_filter.php".

Answer 2

I had the same problem, so I've created a simple input filter which turns the basic syntax of

/**
 * @var int
 */
public $id;

into

/**
 * @var int $id
 */
public $id;

which would be redundant anyway. This way the Eclipse IDE can use the same docblock as doxygen.

You can download the input filter from here:

https://bitbucket.org/tamasimrei/misc-tools/src/master/doxygen/filter.php

See the doxygen Manual on how to use an input filter.

The tool also escapes backslashes in docblocks, so you could use namespaces there.