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
R119 - Ruby Miscellany [1181] Good Programming practise - where to initialise variables - (2007-05-09)
[1586] Variable types in Ruby - (2008-03-21)
[1720] Some Ruby lesser used functions - (2008-07-26)
[1889] Ruby mixins, modules, require and include - (2008-11-16)
[1890] MySQL database from Ruby - an example - (2008-11-16)
[3155] Rake - a build system using code written in Ruby - (2011-02-03)
[3428] How many days to Christmas? - (2011-09-09)
[3622] Loading Ruby classes - where does Ruby look? - (2012-02-24)
[3783] Load path, load and require in Ruby, and a change from 1.8 to 1.9 - (2012-06-24)
R050 - Ruby - General [2104] Ruby Programming and Rails - 4 different courses in one - (2009-03-26)
[2227] Learning PHP, Ruby, Lua and Python - upcoming courses - (2009-06-11)
[2504] Learning to program in ... - (2009-11-15)
[2605] Ruby on Rails - a sample application to teach you how - (2010-01-30)
[2826] Ruby - training for automated testing users - (2010-06-25)
[2866] Ruby - how does it compare and where is it the right language? - (2010-07-11)
[3158] Ruby training - some fresh examples for string handling applications - (2011-02-05)
[4294] A bright new gem - updated Ruby training - (2014-09-16)
[4583] Back in the saddle again - excellent open source course from Well House Consultants - (2015-11-26)
Some other Articles
A Walk on the South BankWhat a difference a year makes A year ago today, a server upgrade and a new Perl exampleFancy a weekend away? Try Well House Manor in Melksham, WiltshireRuby Documentation through rdocWhen you should use Object Orientation even in a short program - Python examplezip in PythonBackquote, backtic, str and repr in Python - conversion object to stringLike a bathroom company with no plumbersShould hotel staff sit on the toilet in the customer bedrooms?