Does the closure compiler process the @property tag?

[andrew...@pearson.com]

Is the information at:

https://developers.google.com/closure/compiler/docs/js-for-compiler

up to date with respect to JSDoc tags that the closure compiler processes?

In particular, is @property processed?  If so, how?

[Nick Santos]

@property is a valid jsdoc tag but is not processed in any way.

> --
>
> ---
> You received this message because you are subscribed to the Google Groups
> "Closure Compiler Discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to closure-compiler-d...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.

[michael...@pearson.com]

So closure doesn't recognize

/**
 * A point in 3 dimensional space w/ an x, y and z coordinate.
 * @typedef {Object} ThreeDPoint
 * @property {number} x The x coordinate of a point in 3D space
 * @property {number} y The y coordinate of a point in 3D space
 * @property {number} z The z coordinate of a point in 3D space
 */
ThreeDPoint;

as describing the same type as:

/** @typedef {{x: number, y: number, z: number}} ThreeDPoint */
ThreeDPoint;

The former is how jsdoc says you can document a complex type (http://usejsdoc.org/tags-typedef.html) which is nice when you really should describe what the properties of the object are.

Mike

[Erik Neumann]

In my experience, closure compiler and JSDoc are sort of distant cousins now.  I think JSDoc has lots of expressions that closure compiler doesn't recognize (perhaps even dislikes).  And JSDoc cannot process google closure compiler based code (I've tried, and had some conversations on their email list about this).

I sure wish I could use JSDoc on my google closure compiler code to produce beautiful docs like these:

http://javadoc.closure-compiler.googlecode.com/git/index.html

Here are some notes I wrote for myself about 8 months ago:

<1> jsdoc and google-closure-compiler (GCC) are incompatible. GCC relies on tags:

@interface, @extends, @implements, @inheritDoc, which are not in jsdoc. And GCC docs say not to use extra jsdoc tags:

http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml You may also see

other types of JSDoc annotations in third-party code. These annotations appear in the

JSDoc Toolkit Tag Reference but are currently discouraged in Google code. You should

consider them "reserved" names for future use.

<2> google uses an internal documentation tool with closure compiler, and they haven't

released it

<3> plovr has some support for generating HTML docs, it might be useful, but means

learning yet more tools (ie. plovr)

[Nick Santos]

correction: the "google-styleguide" url is the google style guide.
closure-compiler has a --extra_annotation_name flag for allowing
whatever jsdoc tags you want

[thanpolas]

Here's how to use a typedef with closure

/**

 * Defines the type

 *

 * @typedef {{

 *   x:  number,

 *   y:  number,

 *   z:  number,

 *   }}

 */

my.app.point3d;

...

/**

 * Accepts a 3d point

 *

 * @param {my.app.point3d} point3d

 */

[michael...@pearson.com]

I have been using jsdoc on my closure annotated files. It seems sort of dumb to not try to fully document and then extract that documentation once you've already added the jsdoc annotations required by google closure. So far w/ a little extra work in the annotations I've been able to make it work. I hope I can continue to make it work.

I've used the --extra-annotations for those jsdoc that google closure complains about, such as virtual and abstract.

I keep hoping that the closure compiler will eventually support the jsdoc tags that is doesn't today, such as @virtual and @abstract (and I guess this @typedef {Object} typename @property propname1 @property propname2 syntax which I thought it already supported).

[thanpolas]

i'm not sure what the argument is here. Closure has much reacher ways to describe OO, jsdoc has @abstract===@virtual, GC uses @interface, @implements, @lends and a bunch of other more granular attributes.

[michael...@pearson.com]

thanpolas,
I understand that, but if you just do that, there is no place to describe the individual properties, and the names of a property are not sufficient (although in this particular case they probably are).

However it looks like jsdoc doesn't care how the typedef object is defined, it will still associate the properties so you could do this:

/**
 * point3d for Google Closure (see above for the definition)

 *
 * @typedef {{
 *          x: number,
 *          y: number,
 *          z: number

 *      }} my.app.point3d
 * @property {number} x - The position of the point along the x-axis
 * @property {number} y - The position of the point along the y-axis
 * @property {number} z - The position of the point along the z-axis
 */
my.app.point3d;

which is better and the jsdoc produces this output:



I've embedded an image above, I hope it works.

Mike

[michael...@pearson.com]

There's no argument.
Erik said that he hasn't been able to run jsdoc over the code he's annotated for GC. I was just replying that I have so far been able to do that, and it is very useful to be able to do that, even though it has required a little extra work to keep my code compatible w/ both.

 I wouldn't say that @interface, @implements... etc are more granular than @abstract and @virtual, I'd say they describe different things and I have used tags from both sets in annotating my code.

I would like to see @abstract and @virtual supported by GC (I've used @abstract on some methods defined in my abstract base classes whose implementation is also defined as goog.abstractMethod). They seem like the describe code in a way that I could get some useful warnings from GC when the code doesn't match (such as when a derived class doesn't implement an @abstract method from a base class).

Similarly I would also really like to see the additional tags like @interface etc. that GC has defined supported by jsdoc.

[Tom Payne]

We're using the Closure Compiler annotations with jsdoc (3.2.2).

We have a a couple custom plugins in our jsdoc config to support this, but it basically works.

jsdoc config is here: https://github.com/openlayers/ol3/tree/master/apidoc

Generated doc is here: http://ol3js.org/en/master/apidoc/

[Nick Santos]

I think it's unlikely that closure-compiler will ever support
@property. My basic line of reasoning goes like this:

(1) It's not simply a new syntax. It introduces new type primitives
that didn't exist before (consider /** @type {Foo} @property {Bar} bar
*/)

(2) New type primitives greatly increase the complexity of the type
system overall (not just for the devs, but for any user that writes
type-annotated JS)

(3) A @property annotation that nobody validates is pure and ideal and
infinitely tractable. A real type-checker needs to follow well-defined
rules. Just about every new type operator we've added has gotten the
response "that's useful in fewer cases than I had in my head", because
once someone formally writes out the type relations, they discover all
the contradictions in the original idea.

All of that said, I do understand the fundamental problem you're
trying to solve--adding better descriptions to one-off properties. I
just think that @property does that in a hand-wavey way that's OK for
generating jsdoc but too vague for a type-checker.

[michael...@pearson.com]

Thanks Nick,

I appreciate your taking the time to explain the reasoning behind not supporting @property (in this instance). And thanks for also recognizing the problem I was trying to solve. Perhaps something will come up in the future that can solve my problem without causing more problems than it solves. In any case It seems with a little duplication of property types and names I can still write the @property tags for jsdoc and have the object described for the closure compiler.

Mike