@inheritdoc

[Lee Katz]

Hi, could you all tell me what I am doing wrong with @inheritdoc?  I have an abstract class `Bio.Root` and I have another class that inherits the constructor and adds onto it.  I know that the JS code isn't totally right yet but please help me understand the jsdoc code.

/**

 * @lends Bio.Root

 */

Bio.Root = Class.create(

  /**

   * Bio.Root

   * @class An abstract base class. All BioJS object inherit from it.

   * @param {Array} Options An associative array with options

   * @param {string} Options.nl The expected newline character (default: \n)

   * @param {string} Options.ie If the browser is Internet Explorer (Options.nl will be set to \r\n if so)

   * @constructs

   * @abstract

   * @inheritdoc

   */

{

  initialize: function(args) {

    this.e = Prototype.emptyFunction;

    this.ie = Prototype.Browser.IE;

    this.nl="\n";

    if(this.ie){

      this.nl="\r\n";

    }

    // default options

    this.options = Object.extend({

      BioRoot:true           // test to see if Root is loaded properly

    }, args || { });

  },

...............

Bio.functions.include_once("Bio::Tools::Align");

/**

 * @lends Bio.Tools

 */

Bio.Tools=Class.create(Bio.Root,{

  /**

   * Bio.Tools

   * @class An interface for tools

   * @constructs

   * @extends Bio.Root

   * @inheritdoc

   * @abstract

   * @name Bio.Tools

   * @param {Array} Options An associative array with options

   * @param Options.outEl {Element} The output element

   */

  initialize:function($super,args){

    $super(args);

  

    this.options = Object.extend({

      outEl:false        // output element

    }, this.options);

  }

});

[Jeff Williams]

Hi Lee,

Part of the problem (maybe the whole problem) is the descriptions following the @class tags. That's not how the @class tag works in JSDoc. Any text following the tag is assumed to be the class name.

Try removing the descriptions and see if that helps.

--
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/799ebef6-753c-4867-9364-aedcb4402259%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Lee Katz]

Thanks!  But it is still not inheriting documentation.  I have also noticed that Bio.Root does not show child classes, and I think it should.  This is the current code:

/**
 * @lends Bio.Root
 */
Bio.Root = Class.create({
  /**

   * An abstract base class. All BioJS object inherit from it.
   * @author Lee Katz <lsk...@gmail.com>
   * @class
   * @param {Array} options An associative array with options
   * @param {*} options.something Child variable function, to be determined by the child
   * @constructs
   * @abstract
   */

/**
 * @lends Bio.Tools
 */
Bio.Tools=Class.create(Bio.Root,{
  /**

   * An interface for tools
   * @author Lee Katz <lsk...@gmail.com>

   * @constructs
   * @extends Bio.Root

   * @implements {Bio.Root}

   * @abstract
   * @name Bio.Tools

   * @param {Array} options An associative array with options
   * @param options.outEl {Element} The output element
   */

[Jeff Williams]

I took a closer look and spotted some additional problems, most notably that the @lends tag is in the wrong place and is using the wrong longname. (It needs to refer to the prototype, like "Bio.Root#".)

Here's a simplified, working example that should help you clean things up:

/**

 * Bio namespace.

 * @namespace

 */

var Bio = {};

Bio.Root = Class.create(/** @lends Bio.Root# */ {

    /**

     * Bio.Root constructor.

     * @constructs Bio.Root

     */

    constructor: function() {},

    /**

     * Some Bio.Root method.

     */

    someMethod: function() {}

});

To view this discussion on the web visit https://groups.google.com/d/msgid/jsdoc-users/b1b0a54c-4b86-4157-becc-bb0e18093501%40googlegroups.com.

[Jeff Williams]

And getting back to your original issue: You want the @augments tag to indicate inheritance rather than @inheritdoc.

Putting it all together:

/**

 * Bio namespace.

 * @namespace

 */

var Bio = {};

Bio.Root = Class.create(/** @lends Bio.Root# */ {

    /**

     * Bio.Root constructor.

     * @abstract

     * @constructs Bio.Root

     */

    constructor: function() {},

    /**

     * Some Bio.Root method.

     */

    someMethod: function() {}

});

Bio.Tools = Class.create(/** @lends Bio.Tools# */ {

    /**

     * Bio.Tools constructor.

     * @constructs Bio.Tools

     * @augments Bio.Root

     */

    constructor: function() {},

    /**

     * Some Bio.Tools method.

     */

    anotherMethod: function() {}

});

[Lee Katz]

Thank you!!  It works for Bio.Tools now!

--

Lee Katz, Ph.D.

[Lee Katz]

Actually--I was faked out.  When I really simplified my parameters for Bio.Tools and Bio.Root, I realized that Bio.Tools did not list any parameters in its documentation that it inherited.  Any other ideas...

--

Lee Katz, Ph.D.

[Jeff Williams]

If the constructor takes parameters, you'll have to document the parameters once for Bio.Root and again for Bio.Tools. Not ideal, but that's how it works.

Updated example:

/**

 * Bio namespace.

 * @namespace

 */

var Bio = {};

Bio.Root = Class.create(/** @lends Bio.Root# */ {

    /**

     * Bio.Root constructor.

     * @abstract

     * @constructs Bio.Root

     * @param {string} blah - Some parameter.

     */

    constructor: function(blah) {},

    /**

     * Some Bio.Root method.

     */

    someMethod: function() {}

});

Bio.Tools = Class.create(/** @lends Bio.Tools# */ {

    /**

     * Bio.Tools constructor.

     * @constructs Bio.Tools

     * @augments Bio.Root

     * @param {string} blah - Some parameter.

     */

    constructor: function(blah) {},

    /**

     * Some Bio.Tools method.

     */

    anotherMethod: function() {}

});

[Lee Katz]

Darn.  Ok, thanks for letting me know.  That is pretty much what I wanted to figure out.

--

Lee Katz, Ph.D.