29

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?

Matt Huggins
  • 81,398
  • 36
  • 149
  • 218

1 Answers1

35

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

BinaryButterfly
  • 18,137
  • 13
  • 50
  • 91
Uri Agassi
  • 36,848
  • 14
  • 76
  • 93
  • 2
    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 – max pleaner Jan 27 '17 at 22:43
  • 1
    @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... – Uri Agassi Jan 29 '17 at 06:16
  • @UriAgassi No, the output does not distinguish between regular and keyword arguments. – lulalala Aug 13 '22 at 08:07