How do I document 'classes' when using John Resig's Simple Inheritance?

[Michael Moore]

I think this is probably a re-post, but after >1/2 hour of searching here and StackOverflow I haven't found anything that works, and I'm not sure what I should be searching for. Links to previous discussions or the appropriate section of the docs would be appreciated.

I've got a code base that is built with a modified version of  John Resig's Simple Inheritance. Most of our methods and classes already have JSDoc comments which are great for reading, but I'd like to generate html pages too.

Unfortunately JSDoc produces warnings and the output isn't what I'm hoping for. The docs only show _global_ and Person. _global_ has dance() and swingSword() methods, Person has no methods.

jsdoc -d=./test -a test.js
java -Djsdoc.template.dir=/usr/share/jsdoc-toolkit/templates/jsdoc -jar /usr/share/java/jsrun.jar /usr/share/jsdoc-toolkit/app/run.js -d=./test -a test.js
>> WARNING: Overwriting symbol documentation for: _global_.
>> WARNING: The symbol '_global_' is documented more than once.
>> WARNING: The symbol 'dance' is documented more than once.
>> WARNING: Trying to document extend as a member of undocumented symbol Class.
>> WARNING: Can't augment contributer: Baseclass, not found.
5 warnings.

JSFiddle showing it working: https://jsfiddle.net/1dqumh0a/

/** Simple JavaScript Inheritance
* @class Baseclass
* By John Resig http://ejohn.org/
* MIT Licensed.
*
* http://ejohn.org/blog/simple-javascript-inheritance/
*/
(function(){
    var initializing = false, fnTest = /xyz/.test(function(){xyz;}) ? /\b_super\b/ : /.*/;
   
    // The base Class implementation (does nothing)
    this.Class = function(){};
   
    // Create a new Class that inherits from this class
    Class.extend = function(prop) {
    var _super = this.prototype;
   
    // Instantiate a base class (but only create the instance,
    // don't run the init constructor)
    initializing = true;
    var prototype = new this();
    initializing = false;
   
    // Copy the properties over onto the new prototype
    for (var name in prop) {
        // Check if we're overwriting an existing function
        prototype[name] = typeof prop[name] == "function" &&
        typeof _super[name] == "function" && fnTest.test(prop[name]) ?
        (function(name, fn){
            return function() {
            var tmp = this._super;
           
            // Add a new ._super() method that is the same method
            // but on the super-class
            this._super = _super[name];
           
            // The method only need to be bound temporarily, so we
            // remove it when we're done executing
            var ret = fn.apply(this, arguments);       
            this._super = tmp;
           
            return ret;
            };
        })(name, prop[name]) :
        prop[name];
    }
   
    // The dummy class constructor
    function Class() {
        // All construction is actually done in the init method
        if ( !initializing && this.init )
        this.init.apply(this, arguments);
    }
   
    // Populate our constructed prototype object
    Class.prototype = prototype;
   
    // Enforce the constructor to be what we expect
    Class.prototype.constructor = Class;
   
    // And make this class extendable
    Class.extend = arguments.callee;
   
    return Class;
    };
})();


/**
 * A person is our base class. He likes to dance
 * @class Person
 * @extends Baseclass
 */
var Person = Class.extend({

  /**
   * @constructs
   * @param {Boolean} isDancing Is this person dancing?
   */
  init: function(isDancing){
    this.dancing = isDancing;
  },
  /**
   * Check if a person is dancing or not
   * @returns {Boolean}
   */
  dance: function(){
    return this.dancing;
  }
});
 
 /*
  * A ninja is a sneaky kind of person
  *
  * @class Ninja
  * @extends Person
  */
var Ninja = Person.extend({
  /**
   * @constructs
   */
  init: function(){
    this._super( false );
  },
  /**
   * Check if a person is dancing or not
   * @returns {Boolean}
   */
  dance: function(){
    // Call the inherited version of dance()
    return this._super();
  },
  /**
   * Check if the ninja is swinging his sword (of course he is)
   * @returns {Boolean}
   */
  swingSword: function(){
    return true;
  }
});
 
var p = new Person(true);
console.log("Is person dancing?");
console.log(p.dance()); // => true
 
var n = new Ninja();
console.log("Is ninja dancing?");
console.log(n.dance()); // => false
console.log("Is ninja swingin sword?");
console.log(n.swingSword()); // => true
 

[Jeff Williams]

It looks like you're using a very old, unsupported version of JSDoc. I would encourage you to upgrade to JSDoc 3.

--
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.
To view this discussion on the web visit https://groups.google.com/d/msgid/jsdoc-users/7a4ec6b8-2bd5-421e-8e47-85d11ed9dcc4%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[x...@odoo.com]

Michael, you'll need to use @lends <newclass>.prototype just before the extend parameter:

var Ninja = Class.extend(/** @lends Ninja.prototype */ {
    …
});

so that the property get associated with the new class as instance methods. However you don't have to specify the name of the class in its own jsdoc, the name of the instance variable will be used for that.

You may also need to move your @param to the class description (not sure about that one).