rdoc, darkfish и тег:call-seq:

Question

Я нахожусь в процессе документирования проекта Ruby с помощью rdoc, и я обнаружил форматировщик темных рыб rdoc. Мне действительно это нравится, но :call-seq: тег больше не работает. Вместо этого он помещает буквенную строку :call-seq: в документации, а затем форматирует саму последовательность вызовов как блок кода. Я не хочу просто удалять все блоки:call-seq: из моего кода, так как большая часть моей документации должна ссылаться на имена экземпляров и имена параметров, приведенные в :call-seq: блок. У кого-нибудь еще возникла такая проблема? Что мне делать, и есть ли обходной путь? Я уверен, что :call-seq: тег работал раньше, когда я использовал форматтер по умолчанию, но я не уверен, потому что не могу понять, как вернуться к генерации исходного формата (вызов rdoc без аргументов, кроме файлов, теперь генерирует вывод darkfish, даже если Удаляю папку doc!) Кто-нибудь знает как это исправить?

Answer 1

Я настоятельно рекомендую перейти от rdoc к YARD. Он не поддерживает сам старый call-seq, но вместо этого у него есть теги, и в особенности тег @overload превосходно заменит call-seq. Вся документация на http://rubydoc.info/ также генерируется с использованием YARD.

Вот пример @overload из документации YARD:

# @overload set(key, value)
#   Sets a value on key
#   @param [Symbol] key describe key param
#   @param [Object] value describe value param
# @overload set(value)
#   Sets a value on the default key `:foo`
#   @param [Object] value describe value param
def set(*args)
end