documenting a metaprogrammed superclass

[paddor]

class Relation < ROM::Relation[:sql]
end

This inherits from a dynamically created class. Yard complains about it like this:

[warn]: in YARD::Handlers::Ruby::ClassHandler: Undocumentable superclass (class was added without superclass)
        in file 'lib/mygem/engines/modules/database/sql/acl.rb':18:

        18: class Relation < ROM::Relation[:sql]

I tried using @!parse before and after, like # @!parse class Relation < ROM::Relation, which results in syntax errors, ...

How to do this properly?

• OS: [Enter operating system / version here] Ubuntu 22.04
• Ruby version (ruby -v): ruby 3.2.0 (2022-12-25 revision a528908271) [x86_64-linux]
• YARD version (yard -v): yard 0.9.28

[lsegal]

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.