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

Question

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

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

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

Answer 1

Похоже, что теперь у 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

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

Answer 2

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

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

--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, который будет анализировать вывод аннотированных моделей.