Home Accessibility Courses Twitter The Mouth Facebook Resources Site Map About Us Contact
Ruby Documentation through rdoc

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.
(written 2012-07-07, updated 2012-07-14)

 
Associated topics are indexed as below, or enter http://melksh.am/nnnn for individual articles
R050 - Ruby - General
  [4294] A bright new gem - updated Ruby training - (2014-09-16)
  [3158] Ruby training - some fresh examples for string handling applications - (2011-02-05)
  [2866] Ruby - how does it compare and where is it the right language? - (2010-07-11)
  [2826] Ruby - training for automated testing users - (2010-06-25)
  [2605] Ruby on Rails - a sample application to teach you how - (2010-01-30)
  [2504] Learning to program in ... - (2009-11-15)
  [2227] Learning PHP, Ruby, Lua and Python - upcoming courses - (2009-06-11)
  [2104] Ruby Programming and Rails - 4 different courses in one - (2009-03-26)

R119 - Ruby Miscellany
  [3783] Load path, load and require in Ruby, and a change from 1.8 to 1.9 - (2012-06-24)
  [3622] Loading Ruby classes - where does Ruby look? - (2012-02-24)
  [3428] How many days to Christmas? - (2011-09-09)
  [3155] Rake - a build system using code written in Ruby - (2011-02-03)
  [1890] MySQL database from Ruby - an example - (2008-11-16)
  [1889] Ruby mixins, modules, require and include - (2008-11-16)
  [1720] Some Ruby lesser used functions - (2008-07-26)
  [1586] Variable types in Ruby - (2008-03-21)
  [1181] Good Programming practise - where to initialise variables - (2007-05-09)


Back to
When you should use Object Orientation even in a short program - Python example
Previous and next
or
Horse's mouth home
Forward to
Fancy a weekend away? Try Well House Manor in Melksham, Wiltshire
Some other Articles
A Walk on the South Bank
What a difference a year makes
A year ago today, a server upgrade and a new Perl example
Fancy a weekend away? Try Well House Manor in Melksham, Wiltshire
Ruby Documentation through rdoc
When you should use Object Orientation even in a short program - Python example
zip in Python
Backquote, backtic, str and repr in Python - conversion object to string
Like a bathroom company with no plumbers
Should hotel staff sit on the toilet in the customer bedrooms?
4300 posts, page by page
Link to page ... 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86 at 50 posts per page


This is a page archived from The Horse's Mouth at http://www.wellho.net/horse/ - the diary and writings of Graham Ellis. Every attempt was made to provide current information at the time the page was written, but things do move forward in our business - new software releases, price changes, new techniques. Please check back via our main site for current courses, prices, versions, etc - any mention of a price in "The Horse's Mouth" cannot be taken as an offer to supply at that price.

Link to Ezine home page (for reading).
Link to Blogging home page (to add comments).

You can Add a comment or ranking to this page

© WELL HOUSE CONSULTANTS LTD., 2014: Well House Manor • 48 Spa Road • Melksham, Wiltshire • United Kingdom • SN12 7NY
PH: 01144 1225 708225 • FAX: 01144 1225 899360 • EMAIL: info@wellho.net • WEB: http://www.wellho.net • SKYPE: wellho

PAGE: http://www.wellho.net/mouth/3799_Rub ... -rdoc.html • PAGE BUILT: Thu Sep 18 15:30:25 2014 • BUILD SYSTEM: WomanWithCat