Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

@inheritdoc fails in situation with 2 classes and 2 interfaces #912

Open
myphysicslab opened this issue Feb 7, 2015 · 2 comments
Open
Labels
Milestone

Comments

@myphysicslab
Copy link

The situation is: class D extends class C which implements interface B which extends interface A. The documentation for the method defined on interface A appears in docs for A, B, C, but not in D. (The method appears but without return type or description).

In the following example: SampleSubject extends AbstractSubject which implements Subject interface which extends Printable interface. The problem is the toStringShort method in SampleSubject is lacking documentation.
The resulting documentation can be seen at:
http://www.myphysicslab.com/rmnp/test20150206/out/index.html
Below is the code for this example. Also available at
http://www.myphysicslab.com/rmnp/test20150206/test20150206.js
Using JSDoc 3.4.0-dev (Thu, 22 Jan 2015 23:02:06 GMT)

/** @classdesc An object that has a minimal string representation via
the `toStringShort` method.
* @interface
*/
myphysicslab.lab.util.Printable = function() {};

/** Returns a minimal string representation of this object, usually
giving just identity information like the class name and name of the
object.
@method
@return {string} a minimal string representation of this object.
*/
myphysicslab.lab.util.Printable.prototype.toStringShort;

/** @classdesc A {Subject} notifies its {Observer}s when something changes in the
{Subject}.
@interface
* @extends {myphysicslab.lab.util.Printable}
*/
myphysicslab.lab.util.Subject = function() {};

/** Returns the JavaScript symbol that refers to this {Subject} for usage in a Terminal
script.
@method
@return {string} the symbol of this {Subject}.
*/
myphysicslab.lab.util.Subject.prototype.getSymbol;

/** @classdesc A *reusable forwarding class* which implements the boilerplate code
for a {Subject}.
@constructor
@implements {myphysicslab.lab.util.Subject}
*/
myphysicslab.lab.util.AbstractSubject = function() {};

/** @inheritDoc */
myphysicslab.lab.util.AbstractSubject.prototype.getSymbol = function() {
  return "foo";
};

/** @inheritDoc */
myphysicslab.lab.util.AbstractSubject.prototype.toStringShort = function() {
  return "AbstractSubject";
};

/** @classdesc A class that extends AbstractSubject.
* @constructor
* @extends {myphysicslab.lab.util.AbstractSubject}
*/
myphysicslab.lab.model.SampleSubject = function() {};

/** @inheritDoc */
myphysicslab.lab.model.SampleSubject.prototype.getSymbol = function() {
  return "bar";
};

/** @inheritDoc */
myphysicslab.lab.model.SampleSubject.prototype.toStringShort = function() {
  return "SampleSubject";
};
@hegemonic
Copy link
Contributor

@myphysicslab You have done an excellent job of stress-testing JSDoc's inheritance-related code. :)

I'll see whether another Band-Aid and a fresh piece of chewing gum can keep this thing flying.

@hegemonic hegemonic modified the milestones: 3.3.0, 3.4.0 Feb 8, 2015
@hegemonic
Copy link
Contributor

I don't see a clean way to hack around this bug for JSDoc 3.3.0. Furthermore, the code in jsdoc/augment has already turned into a real mess. I think I'll need to rewrite a large portion of the code for JSDoc 3.4.0, with an eye towards fixing this bug and preventing similar bugs.

# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants