Main Content

Ruby Documentation through rdoc

Archive - Originally posted on "The Horse's Mouth" - 2012-07-07 09:17:55 - Graham Ellis

There are three vital elements in any code of significnat size that you write.
• There's the code itself
• There are programmer's comments which provide an overview of the internals and remarks on how you've done things, why certain decisions were made, known issues for future maintainers, etc
• There's user documentation. The "user" may be a person running your complete applicaton, or may be a programmer who uses your classes / module / methods within his encompassing application.

Supplied with Ruby, you have rdoc which provides you with a tool to extract and format information from your source files and turn it into documentation.

Here's a brief example of rdoc at work. A previous example (food.rb) in which I demostrated a simple class includes a block comment - a section that runs from =begin to =end:

  =begin
  This is a single class in Ruby - we've set up the
  constructor and an accessor method. We've also
  declared that the @itisa member should be accessible
  as a read only property.
  
  See the multifood.rb example for a much extended
  version of this demonstration
  =end

That block comment, in additon to other elements, will be picked up by rdoc and used to generate HTML documentation. Let's see how that generates:

  munchkin:r108 grahamellis$ rdoc food.rb
  Parsing sources...
  100% [ 1/ 1]  food.rb                                                           
  
  Generating Darkfish format into /Library/WebServer/trainee/r108/doc...
  
  Files:      1
  
  Classes:    1 (0 undocumented)
  Modules:    0 (0 undocumented)
  Constants:  0 (0 undocumented)
  Attributes: 1 (1 undocumented)
  Methods:    2 (2 undocumented)
  
  Total:      4 (3 undocumented)
   25.00% documented
  
  Elapsed: 0.2s
  munchkin:r108 grahamellis$ 

And when viewed, you'll see the following:




Documentation is vital in any software project - on our courses, this is stressed right from the first "Hello World" example - the first working program. We run public Ruby courses (different courses for delegates with different backgrounds) at our training centre and hotel in Melksham, Wiltshire and will run private courses on your site if you've got a group of delegates.