Документальные атрибуты модели с двором

Question

я использую ПЛОЩАДКА Чтобы сгенерировать документы для моего приложения Rails с Makrdown в качестве анализатора сценария. Большинство функций документации просто отлично работают прямо из коробки. Тем не менее, я также хотел бы задокументировать атрибуты модели к одному, записать список доступных атрибутов на модели и двух, чтобы описать их семантическое значение.

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

PS Я использовал драгоценный камень Annodate-Models для создания основной схемы схемы в верхней части списка класса, но это не то, что я хочу.

Answer 1

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

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

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

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

Answer 2

Кажется, что у двора теперь есть свои @!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

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