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

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

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

Ответ 1

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

Ответ 2

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

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