Как правильно сформулировать и отобразить документацию, связанную с постоянными значениями?

Question

Я использую Ruby on Rails 3.1.0 и пытаюсь использовать YARD 0.7.4. Я хотел бы задокументировать значения констант, поэтому в моем классе я утверждаю это:

# [Fixnum] Test constant documentation.
TEST_CONSTANT = 1

но вывод HTML после выполнения команды yardoc (или yard doc) следующий:

На изображении выше показано, что документация HTML плохо отрисована / сгенерирована, по крайней мере, не так, как я ожидал. Я прочитал документацию YAML , но у меня все еще есть некоторые проблемы по этому поводу: как лучше составить и отобразить документацию, связанную с постоянными значениями?

Answer 1

Я также столкнулся с этой проблемой, и Google вернул мне этот пост без ответа.Я нашел ответ Лорена Сегала (создателя Yard) на другом форуме: link_to_forum .Для полноты я добавляю это для людей, которые сталкиваются с той же проблемой:

Вы документируете это так же, как вы документируете любой другой объект.Просто поместите комментарии над константой.

# Documentation here
TEST_CONSTANT = 1   

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