Document duck types with multiple methods in YARD

Question

YARD allows me to specify types for method parameters and return values. As I really like to duck type it is nice to see that YARD also supports defining types by specifying methods they must support.

As you can see here, expressions like

#first_method, #second_method

are interpreted as a logical disjunctions. This means an object needs to support #first_method or #second_method or both. This is not what I need.

I would like to be able to specify that an object is required to support both #first_method and #second_method for my parameter. Is there a way to specify this?

Answer 1

There is no idiomatic syntax for specifying a compound duck-type interface. That said, note that all type specifications are really just free-form text; the YARD types parser link given in the question is simply a set of conventional or idiomatic syntaxes for specifying common interfaces. If you think of a smart way to specify these types (and it makes sense to your users), you are free to do so. Perhaps something like #first#second might work, or #first&#second.

My recommendation, however, would be to create a concrete type to wrap this ad-hoc interface. Even if you don't actually use the type in your runtime, it would serve as object in your domain to explain the interface to your users. For example, by creating a class Foo with the two methods #first and #second, and then documenting those two methods, you could now use Foo as your type. You could explain in the Foo class documentation that it is never actually used in code and just exists as an "interface", if that's the case. You could also make Foo a "module" to denote that it is more of an "interface" (or "protocol", if you prefer that language) than a concrete type.