twobob / jsdoc-toolkit

Automatically exported from code.google.com/p/jsdoc-toolkit
0 stars 0 forks source link

Need to support single var statement with commas #283

Closed GoogleCodeExporter closed 8 years ago

GoogleCodeExporter commented 8 years ago
What steps will reproduce the problem?
1. Create a "class" with some private members that looks like this (with 
documentation) :
   /**
    * @class
    * @final
    * @name MyClass
   */
   MyClass = function(a,b,c)
   {
      /**
       * @property {Number} MyClass-x
       * @memberOf MyClass#
       * @private
     */

      var x   = a || 0,

      /**
       * @property {Number} MyClass-y
       * @memberOf MyClass#
       * @private
      */
          y   = b || 0,

       /**
        * @property {Number} MyClass-z
        * @memberOf MyClass#
        * @private
       */

         z   = c || 0;

       /**
        * @property MyClass#echo
        * @memberOf MyClass#
        * @function
        * @public
       */

       this.echo = function() { return [x, ",", y, ",", z].join(""); }
   }
2. Run jsdoc-tookit on this file. . 
3.

What is the expected output? What do you see instead?
You will see warnings, it appears the jsdoc-toolkit thinks that x, y, and 
z are globas when in fact they are not.

What version of the product are you using? On what operating system?
2.3.2 on Windows XP Pro

Please provide any additional information below.

Original issue reported on code.google.com by sean...@gmail.com on 4 Mar 2010 at 6:31

GoogleCodeExporter commented 8 years ago
This is a issue I am aware of, but I don't think there is any reasonable way to 
completely fix it form my side. In 
a simple example it would be simple to address, but that would lead down an 
endless slope of slightly more 
complex examples where it didn't work.

// Simple to parse
var a, b, c;

// A bit harder
var a = f(b, c), b = a || c(b, a), c? c : b(a);

// Hellish
var a = (function(b, c) { var b, c = function(a, b) { var c, a; } })(b, c), b = 
 (function(a, c) { var a, c = function(a, 
b) { var c, b; } })(a, b), c =  (function(b, c) { var c, b = function(b, a) { 
var c, a; } })(a, b);

// And, actually, it can get much worse...

So JsDoc tries to be just slightly helpful in the easiest case:

// Ridiculously simple
var a;
var b;
var c;

But in any other case you can avoid this by properly applying @name tags to 
your symbols. For example you 
can probably accomplish what you want with the following code:

/**
* @class
* @final
* @name MyClass
*/
MyClass = function(a,b,c)
{
  /**
   * @name MyClass-x
   * @type {Number} 
   * @private
   */

  var x   = a || 0,

  /**
   * @name MyClass-y
   * @type {Number} 
   * @private
   */
      y   = b || 0,

   /**
   * @name MyClass-z
   * @type {Number} 
   * @private
   */

     z   = c || 0;

   /**
    * @name MyClass#echo
    * @function
    */

   this.echo = function() { return [x, ",", y, ",", z].join(""); }
}

Original comment by micmath on 14 Mar 2010 at 8:05