Using TomDoc in Ruby, what is the correct way to denote a splat argument?

Question

The TomDoc format fails to give an example of a splat argument - how should it be done?:

# Public: method to check allowed options.
#
# options  - Hash with options to check.
# *allowed - Splat Array with allowed options.
#
# Returns nothing.
def options_check(options, *allowed)
  # code here
end

Answer 1

Lacking a rule from TomDoc, what you have is reasonable. All that's needed is to well document the argument so that users of the method know how to call it.

In this case though I don't think the splat should be part of the name, since it doesn't go along with the call. Better to add a usage example instead, e.g.

# allowed - One or more options
#
# Examples
#
#   option_check({foo: :bar}, :baz, :qux, :quux)