Как я могу сослаться на параметр (тег @param) из другого параметра?

Question

Я использую Ruby on Rails 3.1.0 и гем YARD 0.7.4 для документации. Я хотел бы сослаться на параметр (@param тег) из другого параметра. То есть у меня есть:

# ...
#
# @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

Является ли это возможным? Если так, как я могу сделать это?

Answer 1

Я не знаю много о YARD, но ни один инструмент документирования, который я использовал, не предоставил такой возможности. Я думаю, это потому, что это редко, если вообще нужно.

Вместо этого просто упомяните имя параметра, и из контекста должно быть очевидно, что это параметр, на который вы ссылаетесь:

# 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

Спустя десятилетие все еще не существует способа сослаться на другой параметр, что, я думаю, имеет смысл, поскольку HTML-документы по умолчанию не имеют привязок к параметрам (см. комментарий @rene-saarsoo к другому ответу, если вы хотите использовать якоря), но вы можете сделать его немного красивее.

Использовать<code>paramName</code>теги для применения стилей, и это все, что, по моему мнению, необходимо сделать, если параметр находится в документируемом методе. Пример:

      # 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

Вот как приведенный выше пример выглядит на сгенерированной веб-странице:

Если вы ссылаетесь на параметр другого метода, вы можете использовать ссылку на объект вместе с<code>ярлык.