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

Question

Я не уверен, возможно ли это на самом деле или нет, но я пытаюсь сделать документацию нашего приложения rails более полной, добавив документацию для областей в наших app/models файлах. То, что я пытаюсь сделать, это:

# This is a description of what the scope does and the action that it performs
scope :newest_records, order("created_at desc").limit(50)

И затем, когда я запускаю rdoc над приложением, я хочу, чтобы увидел newest_records в списке как метод открытого класса вместе с более традиционными методами, которые будут документированы как:

# some more documentation about this method
def self.a_class method
  ....
end

EDIT

Я понимаю, что этот вопрос может быть немного двусмысленным. Итак, вот попытка уточнить: в настоящее время, когда я пытаюсь добавить строку комментария над объявлением scope, я не получаю документацию, сгенерированную RDoc для области. Я знаю, что RDoc может выбирать мета-методы / атрибуты, иначе он не будет отображать атрибуты в документах, которые объявлены с attr_accessor. Поэтому мой вопрос заключается в том, как добавить комментарии к своему файлу, чтобы:

• Метод указан в моей документации, сгенерированной RDoc
• Появляется как метод открытого класса (в отличие от метода открытого экземпляра и т. Д.)

Answer 1

После некоторого поиска в Документах RDoc я думаю, что мне удалось ответить на мой собственный вопрос.

Вы можете задокументировать область следующим образом:

##
# :singleton-method:
# Documentation for the scope to explain what it does
scope :newest_records, order("created_at desc").limit(50)

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

Полный синтаксис для документирования мета-методов и т. Д. Приведен в Документация RDoc

Answer 2

Области являются методами класса, поэтому Rdoc делает это правильно. Я бы сказал, что это работает, насколько Rdoc знает.

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