@var in php is not documented (Origin: bugzilla #626105) #3892
Description
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.