Using JSDoc with Google Closure Compiler: @interface tag needed

[Erik Neumann]

Summary: To work on my Google Closure Compiler (GCC) based code, the JSDoc tags that are lacking are @interface, @implements, and @inheritDoc.  There is also a conflict with using the goog.scope feature of GCC.

Thanks Jeff for the tip about putting the union into parenthesis. That worked and I was able to generate docs for my trial package of 18 javascript files.

The biggest issue preventing me using JSDoc now is that interfaces seem to be ignored.  I'm currently converting a 100,000 line project from Java to Javascript (I'm about halfway thru).  GCC has proven to be invaluable.  I use interfaces heavily, and most of the documentation is in the interface files.

I notice that the error message I got previously lists "interface" and "implements" among the strings that it was looking for, which gives me hope.  Ominously, it is not looking for "inheritDoc".

Are there any plans to add the tags @interface, @implements, @inheritDoc to JSDoc3?  Or is this something I should try to do on my own?

Of lesser importance is the conflict with the goog.scope feature.  I'll describe the issue because anyone else trying to use JSDoc with GCC will likely encounter this problem as well.

The goog.scope function allows using just the name of a class (or interface) without the full package name prefix.  For example, I can use the name "DoubleRect", instead of "myphysicslab.lab.util.DoubleRect".  I give an example of using goog.scope at the end of this message.

As an experiment, I added the full package-path-prefix to all the methods and fields of the classes in my trial package of 18 javascript files -- and this works.  Without doing that, JSDoc fails to produce the method or field documentation.

I can see some ways to work around the goog.scope issue.  But without the @interface tags I can't see a way to use JSDoc on my GCC code.

Best regards,

--ErikN

Here is an example usage of goog.scope:

goog.provide('myphysicslab.lab.util.DoubleRect');

goog.require('myphysicslab.lab.util.Vector');

goog.require('myphysicslab.lab.util.UtilityCore');

goog.scope(function() {

var Vector = myphysicslab.lab.util.Vector;

var UtilityCore = myphysicslab.lab.util.UtilityCore;

var NF5 = myphysicslab.lab.util.UtilityCore.NF5;

/**

@param {!(DoubleRect | Vector | number)} arg1  left edge, 

    or center of rect, or entire DoubleRect to copy

@param {number=} arg2  right edge, or width (when arg1 is center)

@param {number=} arg3  bottom edge or height (when arg1 is center)

@param {number=} arg4  top edge

@constructor

*/

myphysicslab.lab.util.DoubleRect = function(arg1, arg2, arg3, arg4) {

  .... constructor code here ...

};

var DoubleRect = myphysicslab.lab.util.DoubleRect;

/**

* @return {number}

*/

DoubleRect.prototype.getLeft = function() {

  return this.left_;

};

/**

* @return {!Vector}

*/

DoubleRect.prototype.getCenter = function() {

  return new Vector(this.getCenterX(), this.getCenterY());

};

/** Returns a copy of this rectangle translated by the given amount.

@param {!(number|Vector)} x horizontal amount to translate by, or Vector to translate by

@param {number=} y vertical amount to translate by

@return {!DoubleRect} a copy of this rectangle translated by the given amount

*/

DoubleRect.prototype.translate = function(x, y) {

  if (x instanceof Vector) {

    y = x.getY();

    x = x.getX();

  }

  if (!goog.isDef(y))

    throw new Error();

  return new DoubleRect(this.left_ + x, this.right_ + x, 

        this.bottom_ + y, this.top_ + y);

};

... other methods omitted ...

});  // end goog.scope

[mathematical.coffee]

At the moment I don't think JSDoc has @implements/@interface, but some users have synonym'd @interface to @class and @implements to @augments as they are pretty similar.

One could probably write a plugin & modify the default template so that if @interface/@implements was used, the heading is "Interface" or "Implements" rather than "Class" and "Extends" (though I agree, I'd like inbuild @interface/@implements support).

Re @inheritDoc: not currently implemented.

At one point I had a plugin to do this, but its definitions of the tags didn't quite agree with GCC's, and I have not updated it to recent versions of JSDoc so it's quite broken.

There was a bug on this you might like to watch: https://github.com/jsdoc3/jsdoc/issues/53

@ahocevar's comment there may work for you.

Also relevant is this pull request: https://github.com/jsdoc3/jsdoc/pull/417

In particular see the last comment by ErnstHaagman, where he mentions that he has written a "quick-and-dirty plugin to do the job": https://github.com/ErnstHaagsman/jsdoc/tree/inheritparams-plugin

cheers

Amy

(PS: as always, pull requests welcome!)

[Erik Neumann]

Thanks for the ideas, I got a little further but not far enough.

How does one define a synonym in JSDoc?  

I tried doing search/replace to convert @interface to @class and @implements to @augments.  This does get the interfaces appearing in the docs, as classes of course. I could perhaps live with that or do some post-processing search/replace on a list of known interface files.

I tried adding the suggestion of @ahocevar, adding in the plug-in that strips out the @inheritDoc, leaving just a blank comment.  Sadly, it does not have the "strange but useful side effect ... that the inherited docs get applied then."  Instead my (numerous) methods with @inheritDoc appear as though they take no params, return nothing, and have no comments.

The "quick-and-dirty" inheritparams plugin seems to not be relevant to @inheritDoc, but maybe there is a way to use this technique?

What are the chances that Issue #53 "@inheritDoc and @override tags support." could be fixed this year?  It was filed 2 years ago, so is apparently not being worked on.  

OTOH, the Project Road Map item #1 for JSDoc Version 3.2 is:  

Improve compatibility with Google Closure Compiler. (#152)  

Seems to me that supporting @interface and @inheritDoc goes with that goal, no?

I tried glancing thru the code of JSDoc to see if there is any chance I could try to fix this myself.  The code looks very well organized but lacking in documentation, so I don't know where to begin.  Is there any kind of architecture overview for JSDoc to ease someone like me trying to learn the code?  Or tips on where to begin?

I'm guessing that JSDoc works something like this:

1. read all the js sources, and build a representation in memory of the various js pieces: functions, fields, objects, etc

2. read the jsdoc comments and attach bits like @params, @returns, overview descriptions to the js pieces;  connect things together looking at tags like @augments;

3. load the template for how to create the html docs

4. create the html docs by applying the in-memory-representation to the template

Does anyone have hints where in the code these tasks are being done?

My hypothesis is that in step 2 I could look for @inheritDocs on a function and connect up the function to get jsdoc information from a parent function.

Regards,

ErikN

[Jeff Williams]

Hi Erik,

I'm the project maintainer for JSDoc. Sorry to hear that your experience has been frustrating so far.

The upcoming JSDoc 3.2.0 provides much better support for Closure Compiler type expressions. This was not trivial to implement, and I hope it will be helpful to anyone who is using Closure Compiler. I realize that we can improve compatibility further by supporting a few additional tags that are used in Closure Compiler.

The Use JSDoc website has some information about how to write JSDoc plugins that define custom tags. Also, keep an eye on issue #375 (@interface and @implements tags), which is targeted for the JSDoc 3.3.0 milestone.

Yes, issue #53 (@inheritDoc and @override tags) has been around for a while; no, it hasn't been forgotten. It's also targeted for JSDoc 3.3.0.

Explaining the JSDoc internals would take more time than I have right now, but I will say that most of the static analysis code is in the lib/jsdoc/src directory; lib/jsdoc/augment.js and lib/jsdoc/borrow.js do the heavy lifting for inherited/borrowed symbols.

Hope that helps at least a little. In the meantime, thanks for your patience.

- Jeff

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jsdoc-users...@googlegroups.com.
To post to this group, send email to jsdoc...@googlegroups.com.
Visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Erik Neumann]

Hi Jeff,

Thanks for the info.  I was mostly trying to figure out what is the status of using JSDoc with Closure Compiler code.  It's great that JSDoc 3.2 will have better support for the Closure Compiler type expressions.  I imagine that was a big chunk of work.

I read some earlier posts about how the Google Closure Compiler folks adopted the JSDoc syntax without much (any?) consultation with JSDoc project, introducing various changes and no doubt complications from the JSDoc point of view.  Other posts indicate that Google has it's own internal documentation tools which will remain internal.  So Google has little-to-no motivation to get JSDoc working with GCC code and they don't seem to provide any other alternatives (though I did see mention that their plovr tool may have some rudimentary documentation generation feature).

From my point of view it's fantastic that JSDoc is moving on its own towards working with GCC, at whatever speed.

For my own project, it would be great to have docs sometime around October.  Maybe I'll try to dig into plugins or such around then.

Thanks for your work on JSDoc!

--ErikN

[Michael]

Hi Erik,

I'm glad you brought up all those points about Google and JSDoc, because I was about to.

Just to put it in a little more perspective, JSDoc is essentially 1 chap (and a smattering of contributors) who have volunteered to write and give away free software in their free time.

Versus Google.

And personally -- just me here -- I'm not a fan of Closure Compiler, don't ever use it, so if it were up to me that 2 year-old issue in the tracker could happily stay there another 2 years. But if it does that means no one cares enough about it to submit a pull request, and in that case, unworked-on is exactly the right status for that ticket.

I'm sure Jeff appreciates your feedback and comments. I know he accepts pull requests too.

--

Michael

[frontend_dev]

Take a look at @abstract. This could also be used to document interfaces. That's the way I (try to) do right now, at least.