Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Automatically inherit docs from previous def and/or ancestors when missing #6989
NOTE: Final behavior is in #6989 (comment)
This is something that should have been in the doc generator from the beginning.
This PR makes it so that if you don't document a method and that method either redefines a previous method (overwrites it) or is an override (it overrides the method of a superclass), the docs of that other method will be used.
class MyClass # Some docs def foo end end class MyClass def foo end end
In the above case we redefine a method, and the doc generator will use the original doc comments because we are not specifying any.
The other case is:
class MyClass # Some docs def foo end end class MySubclass < MyClass def foo end end
Here we are overriding a method in a subclass, and because we are not specifying any docs the doc generator will use the ones from the superclass.
I think it always makes sense to "inherit" the docs when we don't specify them because the current behavior is not showing anything at all, and that isn't very useful. We either want to inherit the docs (after all, a subclass method should behave more or less the same way as a superclass method) or we want to specify other docs.
Then one could think of having
My other PR about the
I'd also not consider it very useful to just display some documentation of a previous/superclass definition, whose behaviour has most likely changed in some way.
If documentation is implicitly inherited, it can be highly misleading when it plainly states incorrect facts. If there is no documentation at all, it is at least evident that this is missing.
Javadoc implicitly inherits documentation, but adds a reference to the origin:
An overview of the different behaviour can be found in this article: https://christianmoser.me/sinn-unsinn-von-inheritdoc/ The article body is in German but the examples are self-explanatory.
It's also a nice feature to point to the overriden method (regardless of documentation text), but I guess that's for a different PR.
@straight-shoota I like the
What do you think if we do this:
Once we agree, I'll also write tests for this.
I don't see any reason to not inherit the doc from a redefined method by default.
Maybe an explicit
How about injecting the "Description copied from..." notice inside the HTML doc generator, and display it in a different style to make it distinct from the rest of the doc comment (but less visible, not more like
Updated with the behavior described in #6989 (comment)
For a code like this:
class Foo # Some docs for foo def foo end # Some docs for bar def bar end # Some docs for baz def baz end # :nodoc: # I can still document it! def hidden end end class Bar < Foo def foo super end # :inherit: def bar end # The old method did this: # # --- # # :inherit: # # --- # # But this one just rocks! def baz end end
The docs will look like this.
Instance method summary (what you see at the very top):
Instance method detail (what you see below the summary):
@asterite This doesn't seem to work as expected when inheriting from non-methods. I.e. a class/struct or macros.
# Some common docs for Foo abstract class Foo # A macro macro mac end end # :inherit: # # Some specific docs for Bar class Bar < Foo # :inherit: # # Other macro mac end end
Other than that, this is awesome!
Class docs are never inherited and I think it's wrong to do so. I don't believe any language does that.
For macros we don't track overriding, because for macros you must call them like