What support for `@override` tags?

I’m opening this issue in order to clarify what should be the appropriate behavior for @override tags.

As I’m working on making the tests pass on PR#98, I’m a bit confused with the output for the MyThing.copy() override in test/fixtures/class_all.js (see my commit be91778).

According to PR#11, I understand that we should prioritize the parent’s overridden doclet over the downclass’s overriding one (which sounds weird to me).

But according to PR#103, it seems that the port to jsdoc@3.6.3 led us to prioritize the downclass’s overriding doclet over the parent’s overridden one (which seems more logical to me). Indeed, jsdoc@3.6.3 raw output (jsdoc -X) differs from jsdoc@3.5.5, particularly with override doclets, especially with the final module:util~MyThing#copy doclets that receive the first module:util~MyThing#copy doclet in jsdoc@3.6.3 while it received the OtherThing#copy doclet in jsdoc@3.5.5.

If I get back to jsdoc documentation for @override tags, I understand that @override tags could be considered as optional, in as much as jsdoc automatically detects overrides without the help of @override. Nevertheless, when we remove the @override tag in test/fixtures/class_all.js, the raw jsdoc output is different:

• jsdoc@3.5.5:
  • The first module:util~MyThing#copy doclet:
    • no longer has a "override": true attribute,
    • no longer has a "ignore": true attribute,
    • but receives a "overrides": "OtherThing#copy" attribute.
  • The final module:util~MyThing#copy doclet is not generated anymore.
• jsdoc@3.6.6:
  • Same behavior for the first module:util~MyThing#copy doclet.
  • The final module:util~MyThing#copy docletS (two in a row) are not generated anymore.

On the typsecript side, it seems that in the PR#103 version of the test/expected/class_all.d.ts file, typescripts complains with the following error on MyThing.copy():

Property 'copy' in type 'MyThing' is not assignable to the same property in base type 'OtherThing'.
  Type '(other: OtherThing) => void' is not assignable to type '() => void'.

So, even though the PR#103 way looked more logical, it seems that it eventually leads to invalid typescript.

In the end, I have the feeling that ‘explicitly overridden members (i.e. a method that has a different signature)’ as named in PR#11 should not be handled. If so, the @override test case in test/fixtures/class_all.js could be removed.

[englercj]

Yes I think that is what the previous behavior was. If you inherit a method of the same name as one you have defined, we drop the child one.

I don’t feel strongly about the override warning, I’m OK either way.

[Alexis-ROYER]

Fix proposal in PR#98 with commit 8b205c65.