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

Question

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

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

Answer 1

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

Answer 2

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

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