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

• singleton.tgz
• doc/index.html