From: J J <jj5412@...>
Date: 2001-05-06T08:10:09+09:00
Subject: [ruby-talk:14721] Rubydoc?

Is there an existing implementation of Javadoc like comments for Ruby code?
Personally, I find all the =begin, =end, etc. distracting. Well commented
code is virtually unreadable if the comments are placed where the code is
written (where it should be), and is likely not to be maintained if it's
tacked on the beginning or end of the source file in one big lump. Rubydoc
would look like so:

##
# A CheckButton class.
#
# @version $Id: CheckButton.rb 1.3 2001/05/04 16:06:27 john Exp john $
# @author JJ
#
class CheckButton < TkCheckButton
  attr_reader :variable

  ## Pass a block to be executed when the
  #  button is clicked. Also calls onCheck
  #  or onUncheck, as appropriate.
  #
  # @param aBlock A block of code to execute.
  #
  def onClick(&aBlock)
:::

where ## introduces a Rubydoc comment. As you can see, documentation
relevant to a class or method is written where the class or method are
declared. The ## notation is likewise very unobtrusive. Javadoc produces
indexed HTML pages of the documentation extracted from the source code.

In working on OOPierTk I found a need for a better documentation facility.
Sidetracked again!

Regards,
  JJ

--
Be Kind, Be Careful, Be Yourself
--
Solid, reliable software at reasonable prices
http://www.johnjohnsonsoftware.com