Struct subclasses using block form do not get treated like structs

[bdewater]

Steps to reproduce

Came up as part of lostisland/faraday#1489 - in short:

• A subclass of Struct is defined: class Options < Struct; end
• Currently class Env < Options; end is documented as: https://www.rubydoc.info/gems/faraday/Faraday/Env
• Change to Env = Options.new { } as recommended by the Ruby docs results in the Env code being shown inline.

Actual Output

http://localhost:8808/docs/Faraday looks like:

Expected Output

Same treatment as Env = Struct.new { } which results in a separate page.

Environment details:

• OS: macOS 13.1
• Ruby version (ruby -v): ruby 3.2.0 (2022-12-25 revision a528908271) [arm64-darwin22]
• YARD version (yard -v): yard 0.9.28

I have read the Contributing Guide.

[lsegal]

YARD is not an interpreter and thus cannot differentiate between subclasses, as mentioned in that original thread. Struct.new is a hardcoded idiom because it is a standard pattern in Ruby, but there is no reliable way to ensure that Options.new does what Struct.new does without interpreting Ruby code.

You could make the argument that the same is to be said for Struct.new, but in practice overriding the constructor of the Struct class would be far less likely to happen than changing the constructor of an arbitrary class that is not part of the Ruby core library.

Note that this behavior would also differ depending on the order documentation was parsed. Even if we did what is suggested (which would lead to really poor performance in YARD), the docs would be different if your Options class got parsed before the Env = Options.new line vs. after. Since YARD also has no context on how control flows from a standard program (we don't know where the main() function is, as it were), it's entirely possible that Options has not yet been defined upon parsing this line.

I recommend following the suggestions in the original thread, or otherwise use a @!parse directive to shore up the declaration if you are using this type of dynamic behavior.

[bdewater]

Went with the directive since the long term plan is to remove Struct usage entirely. Thanks for the help! 🙌