Documenting Ruby Programs

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:
```
sudo 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: src and 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:

A brief sumary of the design pattern being used.
An image with the complete UML class diagram with all the program’s classes, methods and relationships. You can create this image in the draw.io web site or using any other tool of your preference.
Instructions on how to execute the unit tests.
Optional acknowledgments (if somebody helped you with your program make sure to include her or his name here).
References to all the books and/or web resources consulted while writing the program.

Here’s an example of a README.rdoc file:

= 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.

== 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 img/singleton_uml.png.

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:
```
bash builddocs.sh
```
Use your web browser to see the result, which should be at doc/index.html.

Check the following complete example with all the required source files and its resulting HTML documentation: