Follow these steps in order to document your Ruby programs:
If you haven't done it already, install the Hanna Nouveau Ruby gem. At the terminal type:
gem install hanna-nouveau
If you haven’t done so, create a directory for your program, for example
singleton. Inside this directory, create two subdirectories:
img. All your program source files must go in the
src subdirectory. Place in
img any images you might need for your documentation.
In the root of your program’s directory create a text file called
README.rdoc. This file should contain RDoc Markup. Here you will write the general documentation for your program. It must include:
Here’s an example of a
= Singleton Pattern This documentation was developed as part of a programming activity for the <em>Software Design and Architecture</em> course (_Tc3049_), at the Tecnológico de Monterrey, Campus Estado de México. == Authors * *A00456654* <em>Thursday Rubinstein</em> * *A01160611* <em>Anthony Stark</em> == Overview The <b>singleton pattern</b> is a GoF creational design pattern that ensures a class only has one instance, and provides a global point of access to it. The UML diagram for this programming activity is as follows: rdoc-image:img/singleton_uml.png To test the program, inside the +src+ folder type the following instruction at the command line: ruby -I . -w tigger_test.rb == References - \M. Fowler. <em>UML Distilled: A Brief Guide to the Standard Object Modeling Language, 3rd Edition.</em> Addison-Wesley, 2003. - \E. Gamma, R. Helm, R. Johnson, J. M. Vlissides. <em>Design Patterns: Elements of Reusable Object-Oriented Software.</em> Addison-Wesley, 1994. - \R. Olsen. <em>Design Patterns in Ruby.</em> Addison-Wesley, 2007.
Note that in this example the UML diagram should be placed in a file called
Every Ruby source file, class and public method that is part of your program (even if you didn’t write it yourself) must be adequately documented in comments using Ruby’s RDoc Markup language.
The following code (
src/tigger.rb) shows how a fully documented Ruby source file should look:
# The source code contained in this file demonstrates how to # implement the <em>single pattern</em>. require 'singleton' # A class that models the famous \Tigger character # from A. A. Milne's “Winnie The Pooh” books. class Tigger include Singleton # Returns the string representation of this tigger # instance. def to_s return "I'm the only one!" end # Returns a string with a tigger roar. def roar 'Grrr!' end end
Create a script file called
builddocs.sh in the root of
your program’s directory. Copy the following code to that file:
rm -fR doc rdoc -m README.rdoc -o doc -f hanna src/*.rb README.rdoc cp -R img doc/files
Now, whenever you want to build your documentation, type at the terminal (in your program’s root directory) the following command:
Use your web browser to see the result, which should be at
Check the following complete example with all the required source files and its resulting HTML documentation: