Атрибуты модели документа с YARD

Я использую YARD для создания документов для моего приложения rails с makrdown в качестве парсера script. Большинство функций документации просто отлично работают прямо из коробки. Тем не менее, я также хотел бы документально описать атрибуты модели, записать список доступных атрибутов на модели и два, чтобы описать их семантический смысл.

Я не смог найти какую-либо специальную поддержку для этого в YARD, и в основном я просто перечислял атрибуты в комментариях к классу. Есть ли способ документировать динамически сгенерированные атрибуты модели, чтобы они отображались в документации, например, стандартных атрибутах/методах?

P.S. Я использовал камень annodate-models для создания базового дампа схемы в верхней части списка классов, но это не совсем то, что я хочу.

Ответы

Ответ 1

По прошествии некоторого времени я искал и вручную добавлял документацию для атрибутов в файлы модели. Это, конечно, не идеально, но, надеюсь, структура модели не изменится очень много.

Я создал файл .yardopts для проекта и использовал параметры командной строки ярда для создания двух новых тегов для их маркировки:

--type-name-tag 'attribute:Attributes' --type-name-tag 'association:Associations'

Они предоставляют мне специальные теги для маркировки атрибутов и ассоциаций; они будут отображаться в заголовках "Атрибуты" и "Ассоциации" в документации. Я могу добавить это:

# @attribute name [String] The name of the object
# @association relatedObjs [Array<AnotherClass>] Objects needed to perform a certain function

Возможно, кто-то напишет плагин для YARD, который будет разбирать выходные данные аннотатных моделей.

Ответ 2

Кажется, что для этой цели у YARD теперь есть свой тег @!attribute (обратите внимание на восклицательный знак):

http://rubydoc.info/docs/yard/file/docs/Tags.md#attribute

Пример:

class Task < ActiveRecord::Base
  # @!attribute name
  #   @return [String] The name of the task.

  # @!attribute description
  #   @return [String] The description of the task.

  # @!attribute active
  #   @return [Boolean] Marks whether the task is active or not.
end

Это приведет к хорошей документации ваших атрибутов. Единственное, на что нужно обратить внимание, это то, что вы всегда обновляете свою документацию, потому что никто не будет проверять, удаляете ли вы атрибут из своей документации при удалении из базы данных и т.д.