How can I refer to a parameter ('@param' tag) from another parameter?

Question

I am using Ruby on Rails 3.1.0 and the YARD 0.7.4 gem for documentation purposes. I would like to refer to a parameter (@param tag) from another parameter. That is, I have:

# ...
#
# @param [String] argument_1
#   Here I would like to have a description text with a reference/link to the
#   'argument_2' parameter (see below)...
#
#   Maybe here I can use something like '@param', '{}' or '@macro'... but, how?
#
# @param [String] argument_2
#   Some description text...
#
def method_name(argument_1, argument_2)
  ...
end

Is it possible? If so, how can I make that?

Answer 1

I don't know much about YARD, but no documentation tool I've used has provided such an ability. I guess that's because this is rarely if ever really needed.

Instead just mention the name of the parameter and it should be obvious from the context that it's the parameter that you are referring to:

# True when number is between given min and max values.
# @param [Number] min
# Must be smaller or equal to max.
# @param [Number] max
# Must be larger or equal to min.
def between?(min, max)
  min <= self && self <= max
end

Answer 2

A decade later, there still does not appear to be a way to reference another parameter, which I think makes sense as the default html docs do not have anchors to parameters (see @rene-saarsoo's comment on the other answer if you want to use anchors), but you can make it look a bit nicer.

Use <code>paramName</code> tags to apply styling, which is all that I think needs to be done if the parameter is in the method that is being documented. Example:

# Adds <code>a</code> and <code>b</code>.
#
# @param a [Integer] a number that will be added to <code>b</code>
# @param b [Integer] a number that will be added to <code>a</code>
def add(a, b)
  a + b
end

Here's what the above example looks like on the generated webpage:

If you are referencing a parameter of another method, you can use an object link alongside the <code> tag.