Как оформить заявку на рельсы?

Question

Я только начал документировать приложение рельсов.Я знаю, что на самом деле это делает rdoc, поэтому я следовал некоторым руководствам rdoc относительно синтаксиса и т. Д., Но я застрял, когда попытался описать атрибуты моделей, валидации и отношения между моделями, главным образом потому, что эти вещи являются частью ActiveRecord.Поэтому мне интересно, есть ли какое-нибудь руководство или хорошая практика относительно того, как документировать приложение rails или есть что-то, что я пропускаю?

Я знаю, что я мог бы поместить все это в описание класса, ноИнтересно, есть ли способ, более тесно связанный с самим объявлением (has_many, validates_presence_of и т. Д.) И как насчет атрибутов?

Answer 1

Я лично предпочитаю YARD - http://yardoc.org, так как он лучше справляется с документированием ИМХО. Я не знаю, есть ли конкретный обработчик для Rails, но написать его довольно легко - http://yardoc.org/guides/extending-yard/writing-handlers.html Хорошим примером может служить обработчик атрибута - часть ярда ярда: Библиотека / двор / погрузчики / рубин / attribute_handler.rb

Answer 2

Помните, что ваши тесты являются частью документации (для разработчиков), особенно если вы используете Cucumber, где сценарии легко читаются.Если вы держите ваши методы очень короткими, и есть тестовый метод с описательным именем, например, "должен установить имя пользователя", я нахожу, что мне обычно не нужны комментарии к методу.Я бы не документировал.Часть того, чтобы быть разработчиком Rails, понимает, как они работают, я думаю, это справедливое предположение, что другой сопровождающий вашего кода, читающий его в будущем, будет знать валидации или другие вещи, встроенные в Rails.По той же логике, если вы можете использовать функции инфраструктуры или удачные пути (не сильно отклоняясь) с [задокументированным] сторонним кодом, большая часть документации будет написана для вас.