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.

Answer 3

It seems to be a bug in Doxygen. I've the same problem with documentation in HTML.

What currently works is:

class A
{
    var $id = 1; /**< Id on page. */
}

But these comments are not recognized by NetBeans IDE as documentation of field.

Answer 4

While this is not a direct answer to your question: If you are at liberty to use the right tool for the job, have a look at DocBlox. It also generates an XML-document for further transformation into HTML or any other display format and works very good for PHP. It won't break your usual docblock-usage either.

As an example output, check out the Zend Framework API documentation.

Answer 5

The block will be associated correctly if you omit @var. That doesn't give anywhere to declare the type, which is annoying, but at least the description will work.

Test version: Doxygen 1.7.1

Answer 6

Big thanks to Goran for his doxygen filter! Extending the same idea a bit, to make proper documentation of function parameters as well:

Include Zend Studio-style array-of-objects @param types in doxygen documentation:

// Change the following:
// /** @param VarType[] $pParamName Description **/
// function name(array $pParamName) {

// Into:
// /** @param array $pParamName Description **/
// function name(VarType[] $pParamName) {
$regexp = '#\@param\s+([^\s]+)\[\]\s+(\$[^\s]+)\s+([^/]+)/\s+(public|protected|private)?\s+function\s+([^\s]+)\s*\(([^)]*)array\s+\2([^)]*)\)(\s+){#s';
$replac = '@param array ${2} ${3}/ ${4} function ${5} (${6} ${1}[] ${2}${7})${8}{';
$lSource = preg_replace($regexp, $replac, $lSource);

Include int/float/double/string @param types in doxygen documentation:

// Change the following:
// /** @param (int|float|double|string) $pParamName Description **/
// function name($pParamName) {

// Into:
// /** @param (int|float|double|string) $pParamName Description **/
// function name((int|float|double|string) $pParamName) {
$regexp = '#\@param\s+(int|float|double|string)\s+(\$[^\s]+)\s+([^/]+)/\s+(public|protected|private)?\s+function\s+([^\(\s]+)\s*([^)]*)(\(|,)\s*\2([^)]*)\)(\s+){#s';

$replac = '@param ${1} ${2} ${3}/ ${4} function ${5}${6}${7}${1} ${2}${8})${9}{ '; //${6}${1} ${2}${7})${8}{';
$lSource = preg_replace($regexp, $replac, $lSource);

Both of the above regexps also naturally work with functions taking more than one argument. Also just a quick hack, which works for our code, hope it helps someone else.

Answer 7

For windows users without installed php may be usefull use compiled to executable php_var_filter.php doxygen filter script from answer