rdoc, darkfish и: call-seq: tag

Question

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

Answer 1

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

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

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