Shouldn't @override be supported?

[kedarmhaswade]

Yardoc should support @override on methods when a subclass is overriding a method with the same name in the superclass.

[lsegal]

And what would this do? Defining the override tag can be done via command-line/.yardopts (--tag override:Override), but there isn't much point to showing this in the docs.

YARD can detect an overridden method without such a tag in most cases, so the only benefit would be to "enforce" a rule that all overridden methods have this annotation (similar to Java). Such a rule wouldn't be enforced by yard itself, but by some other tool or plugin.

[kedarmhaswade]

I will take a look at what .yardopts setting does, but in general, I am not sure I understand what you mean by there isn't much point to showing this in the docs. IMO, it's good if in a hierarchy like A<B<C where C.m() documentation says that it overrides (redefines in Ruby lingo) A.m() (if B does not redefine it) -- and yes, there should be a link to the overridden method.

In Java, the presence of @Override annotation on a method that does not really override a superclass method is a compilation error, but you don't "require" @Override annotation on overriding methods. IOW, there is no enforcement of any kind.

[lsegal]

That was the Java enforcement I was speaking of (the lack of an actual valid override).

Realize that @Override is not at all needed for documentation in Java, and nor is it required by YARD. Javadoc (and the JVM) can detect an overridden method regardless of whether an annotation is present. Therefore, reiterating my original point, the only purpose of @Override (in Java) is to "enforce" that you are correctly declaring an overridden method. This would also be true in YARD. See yard-examples for an actual example of such enforcement.

If you'd like YARD to display overridden method information in the template, that is one thing-- but my point is it doesn't require extra annotations in the docs to achieve.

[lsegal]

I guess ultimately the question is: is this request asking to have the default template include override information, or are you asking for the "@override" tag itself for the lint-style reasons Java has it?

[kedarmhaswade]

I guess I was finding out how I can get the references (links) to the overridden method when I was documenting an overriding method. My intuitive understanding was that I do

@override

def m and I get the desired effect in the generated docs (because I thought that kind of documentation was not generated by default even when yard knows that a method overrides a method from superclass).

[lsegal]

In this case, we wouldn't need an extra tag to specify that a method is overriding another. YARD doesn't list overrides by default (because it's generally not as important), but this is something that could be added in with a plugin.