Document inherited members as instance members

[manuelmazzuola]

Hello,
I've a lot of classes, representing all my resources, like

Product.es6.js

import BaseResource from './../BaseResource'
export default class Product extends BaseResource {
  constructor(self) {
    super(self)
    this.path = 'product'
  }
  aMethod(a = 1) {
    return a;
  }
}

export default class BaseResource {
  retrieve(id) {
    return something;
  }
}

The Product class extends the BaseResource class that contains all the commons methods.

What I'd like to do is to document all the members of Product and of the others resource classes as if it were instanced, for example, I'd like that documentation.js will output something like that:

---

product.retrieve

Retrieve a single resource by id or a set of resources

Parameters

• id Number= id of the resource to retrieve (optional, default undefined)

Examples

var client = new Client()
var listOfProducts = client.product.retrieve()
var singleProduct = client.product.retrieve(10)

product.aMethod

Retrieve something else

Parameters

• a Number= id of the resource to retrieve (optional, default undefined)

anotherResourceThatExtendsBaseResource.retrieve

Retrieve something else

Parameters

• id Number= id of the resource to retrieve (optional, default undefined)

Examples

var client = new Client()
var listOfProducts = client.product.retrieve()
var singleProduct = client.product.retrieve(10)

TL;DR

All I want to do is to prefix the method name with the super class name.
And, if it is possible, to override only the description of the method in the super class.

product.retrieve and anotherResourceThatExtendsBaseResource.retrieve are the same method, but different classes, so I'd like to override the description of the method

[tmcw]

Okay, so this is effectively asking that instead of documenting or inferring the @extends tag and saying "Product extends BaseResource" in the documentation, to display all inherited methods as well. Seems like this would be a useful option, but I'm not 100% on this behavior being default.

[jmakeig]

I think it’s important to be able to see all available methods and properties for a given type, including Object.prototype, in the context of the the class itself. (Also, not just ES2015 classes.) However, I think interleaving them inline would be messy and noisy. Object.prototype itself has 15ish properties. I think JavaDoc gets this mostly right by segregating inherited methods and properties into their own sections, one per ancestor type. (For example.) The inherited methods only display names, not parameters or descriptions. Those are available by clicking through to the parent type.

[sudo-suhas]

Is there any way to show inherited methods by passing an option or flag?

[sudo-suhas]

@tmcw Is it possible to implement it the way typedoc does it? http://typedoc.org/api/

[madorb]

I also agree this is incredibly useful, this is exactly how JavaDoc has worked for a very long time.

See for example: https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Sort.Direction.html

Let's say I have class Fruit which is extended by Apple and Banana. Apple is further extended by Gala and Granny Smith
For class Granny Smith it breaks its methods down like:

• Method Summary
  • (methods defined on Granny Smith)
  • Methods Inherited From Apple
  • Methods Inherited From Fruit

Then i can click into any of them and see the appropriate detail