5

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?

user12882
  • 4,702
  • 9
  • 39
  • 54

2 Answers2

0

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.

garie
  • 796
  • 7
  • 19
-4

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
Rene Saarsoo
  • 13,580
  • 8
  • 57
  • 85
  • So, is there no "really" reason to "try" to accomplish what I would like to (*re-read* the question for more information)? – user12882 Jan 21 '12 at 03:21
  • I think it's generally not worth the effort. But if you really need it, then I guess you could just create an HTML anchor `` tag and link to it with HTML link. – Rene Saarsoo Jan 21 '12 at 22:49