Closed paddor closed 2 months ago
First a technical note here: if you are using the @!parse
directive, you must provide valid Ruby code-- in this case, you are missing an end
token in your class declaration:
# @!parse class Relation < ROM::Relation; end
That said, this won't stop the warning because, in a way, you are already addressing the warning properly, and this is in many senses expected behavior even though it might seem surprising.
The @!parse
directive is orthogonal to any warnings YARD may generate. YARD is warning you that this specific line of code is undocumentable. There is no way to know that your directive is "correcting" the warning, or that you are doing it correctly (more on this below). By the same token, even if the directive was declared correctly, it does not take away from the fact that this line of code will forever remain unparseable by YARD, which is what it is warning you about.
It's worth noting that this is a warning, and if you know about it and have no further actions to take, you can safely ignore it. YARD will show the parent class in the way you've declared it in the parse directive (if done properly).
The underlying more interesting part here is that using ROM::Relation
isn't technically correct:
irb(main):003:0> require 'rom-sql'
=> true
irb(main):004:0> ROM::Relation[:sql]
=> ROM::SQL::Relation
Note that ROM::SQL::Relation
is not the same ROM::Relation
class you are using, and although they may offer the exact same API surface area, it is not fully correct to use that parse line.
This brings me to the crux of the issue, and why YARD warns you about these things: this static tool cannot accurately parse a superclass when the superclass is declared dynamically. For that reason, YARD will always warn about this situation so that you can attentively address it.
In your case, the correct way to address the issue, without warnings would be to avoid dynamism and declare the class using the correct superclass from the start:
class Relation < ROM::SQL::Relation
end
This would both correct the warning as well as your API documentation.
This inherits from a dynamically created class. Yard complains about it like this:
I tried using
@!parse
before and after, like# @!parse class Relation < ROM::Relation
, which results in syntax errors, ...How to do this properly?
ruby -v
):ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-linux]
yard -v
):yard 0.9.28