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:
```
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:

Authors’ personal information (student ID and name).
A brief summary 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.

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

- Ruby-Doc.org. <em>RDoc Markup Reference.</em> {\http://ruby-doc.org/stdlib-2.4.1/libdoc/rdoc/rdoc/RDoc/Markup.html}[http://ruby-doc.org/stdlib-2.4.1/libdoc/rdoc/rdoc/RDoc/Markup.html] Accessed August 17, 2017.

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 into 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: