@var in php is not documented (Origin: bugzilla #626105)

[doxygen]

status NEW severity major in component general for ---
Reported in version 1.7.1 on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

• debug.php (ID 167186)
• documentation_scr1.jpg (ID 167187)
• documentation_src2.jpg (ID 167188)

On 2010-08-05 12:47:57 +0000, thomas.smola@frauscher.com wrote:

Created attachment 167186
test class for documentation

I defined a class like this:

<?php
/** 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
--------------------
        $text
...

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

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

Thanks,
Thomas

On 2010-08-05 12:51:08 +0000, thomas.smola@frauscher.com wrote:

Created attachment 167187
documentation screenshot part 1

On 2010-08-05 12:51:31 +0000, thomas.smola@frauscher.com wrote:

Created attachment 167188
documentation screenshot part 2

On 2010-08-05 13:01:40 +0000, thomas.smola@frauscher.com wrote:

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

On 2011-03-01 07:35:23 +0000, Alexander Schilling wrote:

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.

On 2011-05-16 10:05:01 +0000, Giuseppe wrote:

Yes, it seems does not work @var and the description of  variable (public,
protected or private).
It works only with phpDoc... :(

On 2011-05-25 18:00:02 +0000, Edward Rudd wrote:

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

On 2011-05-25 18:05:50 +0000, Edward Rudd wrote:

And here is the explanation of WHY it's doing this..

(documentation for @fn which @var is treated as)
http://www.stack.nl/~dimitri/doxygen/commands.html#cmdfn

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.

On 2011-12-12 09:34:24 +0000, Goran Rakic wrote:

*** Bug 656778 has been marked as a duplicate of this bug. ***

On 2011-12-12 18:13:45 +0000, Goran Rakic wrote:

I've posted a workaround on StackOverflow:
http://stackoverflow.com/a/8472180/276152

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.

On 2016-08-01 07:39:12 +0000, Josef Kufner wrote:

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.

On 2018-05-11 10:12:16 +0000, albert wrote:

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:
<?php
/** \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.

On 2018-05-11 10:41:35 +0000, albert wrote:

Regarding the documentation omission:
I've just pushed a proposed patch to github (pull request 718,
#718).

On 2018-05-11 14:34:57 +0000, Magnus wrote:

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

into 

/**
* @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 ;).

On 2018-05-11 14:38:49 +0000, albert wrote:

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.