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?

Chicken

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

Palaeo

What do you mean "yard recognizes keyword arguments"? The syntax you show is the exact same as non-keyword argument. Does Yard even enforce the contract between params and docstring? And wouldn't it be confusing if a method wanted a keyword arg but is documented as having a regular, sequential argument – Manisa

@maxple I haven't touched ruby in awhile, but have you looked at the rendered output of yard for this syntax? I believe there the keyword arguments are rendered differently than sequential arguments... – Palaeo

@UriAgassi No, the output does not distinguish between regular and keyword arguments. – Tavi