Feature request: support for abstract/overridden methods

[GoogleCodeExporter]

This would be used for documenting classes that are designed to be
subclassed and where only subclasses should be instantiated. Subclasses are
expected to provide certain methods named on the parent class. The parent
class implements any methods that will generally have common implementation
on all subclasses, and defines methods that should appear on each class
without implementing them if the subclass must define the implementation.

At the moment, there is no way of specifying this in jsdoc. It would be
nice to be able to tag a class as @abstract and for jsdoc to put a big
notice at the top of the docs somewhere saying this class should not be
instantiated directly.

Also, it would be nice if the "abstract" methods specified in the class
that are overriden by a subclass could get the same documentation comment
as that in the parent class if a comment is not provided. It's annoying
having to copy and paste the comment from the parent class to the child
classes. Not sure if it would be possible to use an @abstract tag on the
parent class for this - if not, maybe some kind of @override tag.

Example code:
/**
 * This class shouldn't be instantiated directly - use one of the subclasses.
 * @abstract
 */
Parent = function() {
   this.id = "parent";
}

/**
 * This method is inherited by sub-classes unless they override it.
 */
Parent.prototype.saySomething() {
   return "Hello from " + this.id
}

/**
 * Does something that only the child class can implement. We know what we
 * want the method to take as input and to return as output and we want all
 * child classes to implement it.
 * @return {String}
 * @abstract
 */
Parent.prototype.doSomethingSpecific() {
   throw "subclass must implement this method"
}

/**
 * @extends Parent
 */
Child = function() {
   this.id = "child";
}
// set up inheritance from Parent here using your chosen method

// the documentation for this method is on the parent class, don't want to 
// write it all again just because we're implementing it here...
Child.prototype.doSomethingSpecific() {
   // implementation goes here
}

Original issue reported on code.google.com by rebecca....@gmail.com on 15 Jun 2009 at 11:02

[GoogleCodeExporter]

Giving a special appearance to classes with an @abstract tag can already be 
accomplished by treating 
@abstract as a custom tag. See: 
http://code.google.com/p/jsdoc-toolkit/wiki/FAQ#Using_custom_tags

As for inheriting documentation, this already happens via the @extends tag (or 
its synonym @augments). In 
the generic jsdoc template this results in links to the inherited members 
appearing in the Child's 
documentation. If you want it to appear as if the inherited member is actually 
implemented in the Child you 
can use the @borrows tag, like so

/**
 * @constructor
 * @extends Parent
 * @borrows Parent#doSomethingSpecific
 */
Child = function() {
   this.id = "child";
}

Original comment by micmath on 21 Jun 2009 at 1:00

• Changed state: WontFix