Allow @var syntax like @param

[Broofa]

It would be really nice if we could use the same syntax to document
@var as we do @param. Not only is this more compact, it more
intuitive in some ways. Several people on my team are doing this
anyway because that's how they assume it should work.

For example:

/** @var {Number} count The total number of items */
var count = 0;

/** @var {Object[]} contents List of all contained items */
var contents = [];

/** @var {Boolean} loaded Flag indicating load state of collection
*/
var loaded = false;

Currently the closest you can get to this compact a form is something
like this, which looks a bit odd

/** The total number of items
* @var {Number} count */
var count = 0;

/** List of all contained items
* @var {Object[]} contents */
var contents = [];

/** Flag indicating load state of collection
* @var {Boolean} loaded */
var loaded = false;

[denis.r...@gmail.com]

That brings up a question - say, the following had been specified

/** There goes long and boring comment
@var {Number} count Here goes something relatively short, although in
this case it is longer than the long and boring comment
*/
How it should be interpreted? What should be rendered in summary and
in details?

Regards,
Denis

[Broofa]

I suppose you could log a warning, but I would just concatenate the
two together (with an empty line between them), giving priority to any
shorter comment that follows @var, since it's more likely to be a
summary. I.e. your example would get treated as though it looked
like this:

/**
* Here goes something relatively short, although in this case it is
longer
* than the long and boring comment
*

* There goes long and boring comment

* @var {Number} count
*/

[denis.r...@gmail.com]

ok, try to get the latest from SVN and let me know if it is what you
expected

Denis

[Broofa]

Hey Denis, sorry to take so long to get back to you on this.

Maybe I'm doing something wrong, but it doesn't look like the latest
trunk build is doing anything described in this thread. E.g I have a
comment:

/** @var {static} MONTHS Locale month names. */

This just gets documented as:

variable static MONTHS

The description doesn't appear anywhere.

[denis.r...@gmail.com]

That's odd. I have tried your sample and it worked for me.
Which version of DocParser do you have? Should be 366 from Jan 10

Denis

[denis.r...@gmail.com]

BTW, the fix from Jan 10 introduced a problem, which should be fixed
now in svn.

Denis