Skip to content
New issue

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

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

Already on GitHub? Sign in 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.

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

No branches or pull requests

2 participants