After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 626105 - @var in php is not documented
@var in php is not documented
Product: doxygen
Classification: Other
Component: general
Other Windows
: Normal major
: ---
Assigned To: Dimitri van Heesch
Dimitri van Heesch
: 656778 (view as bug list)
Depends on:
Reported: 2010-08-05 12:47 UTC by thomas.smola
Modified: 2018-07-30 10:41 UTC
See Also:
GNOME target: ---
GNOME version: ---

test class for documentation (814 bytes, application/php)
2010-08-05 12:47 UTC, thomas.smola
documentation screenshot part 1 (59.97 KB, image/pjpeg)
2010-08-05 12:51 UTC, thomas.smola
documentation screenshot part 2 (75.06 KB, image/pjpeg)
2010-08-05 12:51 UTC, thomas.smola

Description thomas.smola 2010-08-05 12:47:57 UTC
Created attachment 167186 [details]
test class for documentation

I defined a class like this:

/** class for debugging */

class debug {

 	/** @var string Description */
	private $text; 

After generating the documentation via doxygen the datatype of the private variable isn't recognized. The result looks like this:

private attributes

Shouldn't it look like this?:
private attributes
  string $text

Is there any possible workaround or when will this problem be fixed?

Comment 1 thomas.smola 2010-08-05 12:51:08 UTC
Created attachment 167187 [details]
documentation screenshot part 1
Comment 2 thomas.smola 2010-08-05 12:51:31 UTC
Created attachment 167188 [details]
documentation screenshot part 2
Comment 3 thomas.smola 2010-08-05 13:01:40 UTC
In Java or C++ I have following function declaration:

public String getText() {

How can I add the return datatype of a function to the documentation with php??
Comment 4 Alexander Schilling 2011-03-01 07:35:23 UTC
I got the following warning and the member variable is not documented:

php/core/db/Cache.class.php:22: warning: documented function `core::db::Cache::string' was not declared or defined.

my code looks like:

 * Class for caching values.
class Cache

   * Name of the cache
   * @var string
    private static $cache = null;

If I remove the @var line doxygen will work without warning and show the documentation but without the type, of course.
But I need the @var line for the code assist functions in netbeans and eclipse.
Comment 5 Giuseppe 2011-05-16 10:05:01 UTC
Yes, it seems does not work @var and the description of  variable (public, protected or private).
It works only with phpDoc... :(
Comment 6 Edward Rudd 2011-05-25 18:00:02 UTC
I got this working with this syntax

class Mine {
    * Definition of variable
    * @var string $var
   private $var = array();

Though it would make sense to NOT have to respecify the variable name everytime.

This is tested on doxygen 1.7.3
Comment 7 Edward Rudd 2011-05-25 18:05:50 UTC
And here is the explanation of WHY it's doing this..

(documentation for @fn which @var is treated as)

So the issue here is differences between how PHPDoc interprets @var (which all the IDEs seem too go by) and how Doxygen interprets @var..  And of course the frustrating thing is, I like the doxygen output MUCH better than PHPDoc.  So having some kind of PHP "exception" for @var in doxygen would be really appreciated.
Comment 8 Goran Rakic 2011-12-12 09:34:24 UTC
*** Bug 656778 has been marked as a duplicate of this bug. ***
Comment 9 Goran Rakic 2011-12-12 18:13:45 UTC
I've posted a workaround on StackOverflow:

It is just a simple regexp that can be used as input filter to make the member declaration more C-like, and this so, allow Doxygen lexer to get the type info. 

It also removes @var annotation as it has a different meaning with Doxygen than in phpDoc.

Be free to use and extend as public domain and/or the Doxygen license.
Comment 10 Josef Kufner 2016-08-01 07:39:12 UTC
Quick fix: INPUT_FILTER = "sed -e 's/@var\s/@see /'"

It is not perfect, but it can help when more complicated regexps don't fit your code. It is better than omitting the @var altogether since the information about type is not lost, only moved to the description.
Comment 11 albert 2018-05-11 10:12:16 UTC
Regarding the @var the docuenation states (chapter about special commands):

24.51 \var (variable declaration)
Indicates that a comment block contains documentation for a variable or enum value (either global or as a member of a class).

and on the top of the chapter:
• If (round) braces are used the argument extends until the end of the line on which the command was found.

Not documented is the behavior of php regarding the datatype.

A small example here is:
/** \file */

/** @var $v1
  *  variable without data type
$v1 = 7;

/** @var int $v2
  *  variable with data type
$v2 = 7;

/** @var int
  *  just data type
$v3 = 7;


So in my opinion the problem is usage, and the issue can be closed as such.
Comment 12 albert 2018-05-11 10:41:35 UTC
Regarding the documentation omission:
I've just pushed a proposed patch to github (pull request 718,
Comment 13 Magnus 2018-05-11 14:34:57 UTC
Hello, I was seeing this problem and I couldn't solve in anyway.
But seeing that a patch was proposed on git, I'm waiting for it to be approved.

Since the patch indicates that the @var documentation should be as follows (as I understood it):

* @var type
* documentation
scope $var

For those using Eclipse, I believe it doesn't allow you to do this, because it requires that every documentation for unformatted commands (I believe the @var and such commands can't be modified by formatters) has to be on a single line.

So I've created this code/regex for a input filter so that it automatically breaks a line after the TYPE specification:

// inserting a linebreak after '@var type'
$regexp = '/(.+@var .+?)(\s)(.+)/';
$mod = explode( PHP_EOL, $source );
$match = preg_grep( $regexp, $mod );
foreach ( $match as $key => $line )
  $mod[ $key ] = preg_replace( '/(?<!@var)\b(\s)\b/', PHP_EOL . "    *           ", $line, 1 );
$source = implode( PHP_EOL, $mod );

this code turns

* @var int blablabla


* @var int
*           blablabla

If you want to use the $varName also, you just have to modify the regex code a little bit. If you don't use '@' but use '\' instead, just modify the regex too. 

Let's hope this pull gets merged soon ;).
Comment 14 albert 2018-05-11 14:38:49 UTC
The pull request is just small explanation in the documentation. No code changes.
Be aware of the possible side effects of the spaces before blablabla and markdown support.
Comment 15 André Klapper 2018-07-30 10:41:22 UTC
As discussed in , Doxygen has moved its issue tracking to

All Doxygen tickets in GNOME Bugzilla have been migrated to Github. You can subscribe and participate in the new ticket in Github. You can find the corresponding Github ticket by searching for its Bugzilla ID (number) in Github.

Hence I am closing this GNOME Bugzilla ticket.
Please use the corresponding ticket in Github instead. Thanks a lot!