Re: error on non-null type in a union

[Erik Neumann]

I forgot to show the code that was being compiled.  Here it is:

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) {

  var left, right, bottom, top, width, height;

  if (arg1 instanceof myphysicslab.lab.util.DoubleRect) {

    left = arg1.getLeft();

    right = arg1.getRight();

    bottom = arg1.getBottom();

    top = arg1.getTop();

  } else if (arg1 instanceof Vector) {

    // arg1 is the center

    if (!(goog.isDef(arg2) && goog.isDef(arg3))) {

      throw new Error();

    }

    width = arg2;

    height = arg3;

    left = arg1.getX() - width/2;

    right = arg1.getX() + width/2;

    bottom = arg1.getY() - height/2;

    top = arg1.getY() + height/2;

  } else {

    if (!goog.isDef(arg2) || !goog.isDef(arg3) || !goog.isDef(arg4)) {

      throw new Error();

    }

    left = arg1;

    right = arg2;

    bottom = arg3;

    top = arg4;

  }

  if (left > right) {

    throw new Error();

  }

  if (bottom > top) {

    throw new Error();

  }

  /**

  * @type {number}

  * @private

  */

  this.left_ = left;

  /**

  * @type {number}

  * @private

  */

  this.right_ = right;

  /**

  * @type {number}

  * @private

  */

  this.bottom_ = bottom;

  /**

  * @type {number}

  * @private

  */

  this.top_ = top;

};

var DoubleRect = myphysicslab.lab.util.DoubleRect;

(there is more...)

 --ErikN

On Thursday, May 30, 2013 12:13:05 PM UTC-7, Erik Neumann wrote:

The JSDoc dictionary (at http://usejsdoc.org/tags-type.html ) states that ! is a valid character in a type.  Yet I'm getting an error on 

@param {!DoubleRect | !Vector | number}

I'm trying to run JSDoc on my Google Closure Compiler code.  I've read bits and pieces about how JSDoc is moving towards compatibility with Closure Compiler, so I'm aware that it is probably not going to work.  But I thought I'd try it and see what happens.

Following some advice on https://github.com/jsdoc3/jsdoc/issues/152  "Parse Google Closure type annotations correctly" I'm using the --lenient option.  Here is the command and the results:

$ ./jsdoc -v

JSDoc 3.2.0-dev (Fri, 19 Apr 2013 22:04:23 GMT)

$ ./jsdoc -l ../jssimlab/src/lab/util/DoubleRect.js 

Error: cannot create a doclet for the comment "/**@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*/": unable to parse the type expression "!DoubleRect | !Vector | number": Expected "$", "*", "...", "?", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter or Unicode uppercase letter but "!" found.

TagValueRequiredError: The @description tag requires a value. File: undefined, line: undefined

There are more errors, but they all seem to be complaining about a "!" in a type.  Perhaps ! doesn't work in a union type?  Or perhaps I need a newer version than the pre-packaged "latest development version"? 

Thanks,

--ErikN

[Jeff Williams]

Hi Erik,

You're seeing this error because, according to Google's docs, type unions should be enclosed in parentheses. If you omit the parentheses, the type parser will do its best to parse the type expression, but it won't always succeed.

I verified that JSDoc does not throw an error when you add the missing parentheses:

/**

 * Foo function.

 * @param {(!DoubleRect | !Vector | number)} bar - The bar parameter.

 */

function foo(bar) {}

The current version of JSDoc does not preserve the nullable types in this case--it treats each parameter as either nullable or non-nullable, not conditionally nullable. I may try to address this for the upcoming 3.2 release.

- Jeff

On Thu, May 30, 2013 at 12:13 PM, Erik Neumann <neu...@gmail.com> wrote:

The JSDoc dictionary (at http://usejsdoc.org/tags-type.html ) states that ! is a valid character in a type.  Yet I'm getting an error on 

@param {!DoubleRect | !Vector | number}

I'm trying to run JSDoc on my Google Closure Compiler code.  I've read bits and pieces about how JSDoc is moving towards compatibility with Closure Compiler, so I'm aware that it is probably not going to work.  But I thought I'd try it and see what happens.

Following some advice on https://github.com/jsdoc3/jsdoc/issues/152  "Parse Google Closure type annotations correctly" I'm using the --lenient option.  Here is the command and the results:

$ ./jsdoc -v

JSDoc 3.2.0-dev (Fri, 19 Apr 2013 22:04:23 GMT)

$ ./jsdoc -l ../jssimlab/src/lab/util/DoubleRect.js 

Error: cannot create a doclet for the comment "/**@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*/": unable to parse the type expression "!DoubleRect | !Vector | number": Expected "$", "*", "...", "?", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter or Unicode uppercase letter but "!" found.

TagValueRequiredError: The @description tag requires a value. File: undefined, line: undefined

There are more errors, but they all seem to be complaining about a "!" in a type.  Perhaps ! doesn't work in a union type?  Or perhaps I need a newer version than the pre-packaged "latest development version"? 

Thanks,

--ErikN

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

[Jeff Williams]

On second thought, after more coffee:

I don't think it makes sense to say that a parameter is "conditionally nullable" or "conditionally non-nullable." Either it can be null sometimes, or it can't, right?

So I think this is more correct:

/**

 * Foo function.

 * @param {!(DoubleRect | Vector | number)} bar - The bar parameter.

 */

function foo(bar) {}

With that type expression, JSDoc will correctly document bar as a non-nullable parameter.

- Jeff

[Michael Mathews]

In your example, would that make "!" mean? (DoubleRect | Vector | number | null}

Michael Mathews
mic...@gmail.com

[Jeff Williams]

Because "!" indicates "non-nullable," I think my example means "DoubleRect, Vector, or number, but never null."

In the land of Closure Compiler, my understanding is that everything is assumed to be nullable unless you specify otherwise. However, you can use the "?" operator to explicitly state that something is nullable.

- Jeff

[Michael Mathews]

So exactly what I said, but opposite. (Why is it always like that?)

Okay, so in that case it makes no sense to me to ever say: (!DoubleRect | !Vector | number) == "DoubleRect, but never null OR Vector, but never null OR number, and sometimes null". I think your coffee was right.

[Daniel Meyer]

For posterity (i.e. in case someone else searches and finds this like I did :-), in Closure:

"functions and all value types (boolean, number, and string) are non-nullable by default", per https://developers.google.com/closure/compiler/docs/js-for-compiler#nonnull