Doxygen: how to describe class member variables in php?

I'm trying to use doxygen to parse php code into xml output. Doxygen does not 开发者_JAVA百科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?

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".

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.

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.

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.

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

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.

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