Как документировать приложение Rails?

Question

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

Я знаю, что я могу поставить все это в описании класса, но мне интересно, есть ли путьнее, привязанный к самой декларации (HAS_MANY, Validates_Presence_of и т. Д.) А как насчет атрибутов?

Answer 1

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

Answer 2

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

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