documenting arguments that can be arrays

[Mark Hubbart]

Hi, a bit of a newbie to YARD here.

How do you document a method that takes either an argument, or an array of arguments? My current straightforward way:

# @param names [<Symbol,#to_sym>] the list of names to start with
# @param change [Symbol,#to_sym,nil,(Regexp,String),<Symbol,#to_sym,nil,(Regexp,String)>]

def foo(*names, change:)

The duplication on `@param change` seems a bit verbose, and possibly to the point of reduced clarity... Is there another way of doing it? I guess I could use overload, but that would make it even more verbose.

Thanks,

Mark

[Loren Segal]

Hey Mark,

I would suggest an overload in this case, actually. That would make it much more clear about the two distinct ways this API can be used. 

The alternate suggestion would be to simplify your API such that you either *only* accept an Array, or, more likely, *only* accept a splat (and leave it up to the user to handle the arr-to-splat conversion on their end). That makes for a more succinct less error prone API. Not sure if it's too late to do this, though.

- Loren

--

---
You received this message because you are subscribed to the Google Groups "YARD" group.
To unsubscribe from this group and stop receiving emails from it, send an email to yardoc+un...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.