How should I provide YARD/RDoc documentation for Ruby keyword arguments?

Question

For a basic Ruby method, I would provide YARD style doc for parameters in the following format.

# @param query [String] The search string to query.
# @param options [Hash] Optional search preferences.
def search(query, options = {})
  # ...
end

With Ruby 2.0, keywords arguments can now be used. However, I'm not sure how to approach that in terms of the YARD documentation.

def search(query, exact_match: false, results_per_page: 10)
  # ...
end

How would I document for exact_match and results_per_page in the second scenario? Should I just continue to use the @param keyword, or is there something better?

Answer 1

Should I just continue to use the @param keyword?

Yes.

---

YARD recognizes keyword arguments. Use @param to document a single method parameter (either regular or keyword) with a given name, type and optional description:

# @param query [String] The search string
# @param exact_match [Boolean] whether to do an exact match
# @param results_per_page [Integer] number of results
def search(query, exact_match: false, results_per_page: 10)
  # ...
end

Source: YARD Tags @param at rubydoc.info