Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to document a rails application?

I just started to document a rails application. I know this is actually done by rdoc, so I followed some rdoc guides regarding syntax and so on, but I got stuck when I tried to describe attributes of models, validations and the relationship between models, mostly because these things are part of ActiveRecord. So I wonder if there is some guide or a good practice regarding how to document a rails application or if there is something I'm missing?

I know that I could put all of this in the class description, but I wonder if there is a way more closely tied to the declaration itself (has_many, validates_presence_of, etc.) and what about the attributes?

like image 675
ramontiveros Avatar asked Nov 02 '10 02:11

ramontiveros


People also ask

How do I run a Rails application?

Go to your browser and open http://localhost:3000, you will see a basic Rails app running. You can also use the alias "s" to start the server: bin/rails s . The server can be run on a different port using the -p option. The default development environment can be changed using -e .

What are APIS in rails?

What is an API Application? Using Rails as an API means a user is provided a web application and also an accessible API. An Application Programming Interface (API) is a computing interface that defines interactions between multiple software intermediaries.

How do I create a controller in Rails?

To generate a controller and optionally its actions, do the following: Press Ctrl twice and start typing rails g controller. Select rails g controller and press Enter . In the invoked Add New Controller dialog, specify the controller name.


2 Answers

I personally prefer YARD - http://yardoc.org , as it does a better job in documenting IMHO. I don't know if there's a specific handler for Rails available, but it's quite easy to write one - http://yardoc.org/guides/extending-yard/writing-handlers.html A good example might be the attribute handler - part of the yard gem: lib/yard/handlers/ruby/attribute_handler.rb

like image 164
Roman Avatar answered Oct 17 '22 15:10

Roman


Remember your tests are part of the documentation (for developers), particularly if you are using Cucumber where scenarios are easy to read. If you keep your methods very short and there is a test method with a descriptive name e.g. "should set the users name" I find I typically don't need comments on the method.

Validations or other parts of Rails I would not document. Part of being a Rails developer is understanding how these work, I think it is a fair assumption that another maintainer of your code reading it down the road will know validations, or other things built in to Rails. By that same logic, if you can use features of the framework or happy paths (not deviate much) with [documented] third party code, a lot of the documentation will be written for you.

like image 40
Andy Atkinson Avatar answered Oct 17 '22 14:10

Andy Atkinson