Overriding methods has no way to inherit the parameter documentation from the superclass

Search Terms

override param parameters doc documentation function method extends

The Problem

class CoolClass {
	/**
	 * I'm some neat and cool JSDoc info about `method`!
	 * @param arg I'm some information about an argument
	 */
	method (arg: any) {}
}

class NotAsCoolClass extends CoolClass {
	method (arg: any) {}
}

In this code example, method gets the following documentation:

I'm some neat and cool JSDoc info about `method`!

It does not get @param documentation (or any other @ documentation parameters). However, this would be very, very helpful to have. The main use case I have for it is for a modding API for my project. The way we currently handle it is we have an interface containing all our “hook” methods, and then a “Mod” class that implements that interface. All the hook methods on it are called by our code internally.

A modder can extend the Mod class to hook into the base code. The works great for us, however, this means that the documentation we have on the hook methods is only the method description and nothing about the parameters of the hooks (which is pertinent information).

Suggestion

Keep the @param information on methods without other documentation

I assume the main reason the information isn’t currently kept is because subclass methods can do different things with the parameters. However, throwing them out all the time is a bit of an extreme solution. I suggest that if the subclass doesn’t provide it’s own documentation, it should keep all documentation from the superclass method. I think that 100% of the time it would be more useful for it to work this way.

Checklist

My suggestion meets these guidelines:

• This wouldn’t be a breaking change in existing TypeScript / JavaScript code
• This wouldn’t change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn’t a runtime feature (e.g. new expression-level syntax)

[samschurter]

It may be semi-resolved, but the overriding method still does not get the type of the param from the parent in the signature.

It has also not inherited the type for type hints on the variable in the method body:

[htho]

It may be semi-resolved, but the overriding method still does not get the type of the param from the parent in the signature.

So you’d like to be able to override methods and not add types to parameters because the types could be inherited from the parent class?

Interesting point. The information is redundant, therefore it could be done.

On the other hand: If I change a type in a parent class, errors would pop up not in the signature (incompatible signatures) but in the implementation. This would make it much harder to actually find the reason for the problem. Worst-case is, there is no error at all, because the implementation just happens to use the parameter in a way that is compatible with the new type. But the behavior changes without the developer noticing.

BUT: This is not the topic of this Issue.

IMO this one can be closed.