-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Overrides of public API methods should be documented #11085
Comments
What about omitting the docs altogether, or I made a patch that detects such
plus 14 more for defs from root types: (I'd argue these defs can implicitly inherit their docs from parents, like the
The patch is here. There is the option of enforcing this in the style guide and the docs generator for any shards out there. |
I think omitting documentation (which implicitly inherits from the parent def) or an explicit I like adding a warning to the doc generator 👍 |
If #11089 is intended behaviour then one cannot assume that omitting doc comments implies the documentation is missing, because the generated docs are visibly different between no comments at all and a bare |
Overrides of public API methods are also public API and thus should be documented themselves.
An example is
Array#index(object, offset : Int = 0)
which overridesIndexable#index(object, offset : Int = 0)
but is designated as:nodoc:
:crystal/src/array.cr
Lines 2271 to 2272 in 5410318
If you call
index
on anArray
, the API docs would show that this method is implemented inIndexable
, when it is in fact overridden inArray
. When there's an error with calling that method, the compiler would show it resolved toArray#index
, but this method can't be found in the public API docs.This method overrides the previous implementation for a reason. The documentation can't really be identical, because it does something different.
So not only should it be documented, the differences to the original implementation should also be mentioned in the documentation.
The text was updated successfully, but these errors were encountered: