RDoc comment style

+------------------------------------------------------------------------------+
| RUBY COMMENT STYLE RECOMMENDATIONS                                           |
+------------------------------------------------------------------------------+

 Although RDoc isn't brilliant it is passable and until it improves (see RDoc
 2 in Ruby 1.9 for what is happening in the future) I say we stick to it.

 Features of this coding comment style:

 * provides a clean documentation style that allows for easy recognition of
   where classes and methods start.
 * method and class names in comments line up with their corresponding
   definitions for easy visual parsing/recognition.
 * Hardly any extra clutter just for documentation purposes, yet RDoc output
   is nice to read.
 * grep for '#--==' in ruby source will give a list of all classes and modules
 * grep for '#-- ' will list all methods (note the trailing space)
 * takes advantage of the '#--' disable feature to avoid cluttering RDoc output

+------------------------+
| CLASS/MODULE COMMENTS: |
+------------------------+

 If you want to clearly mark the start of a new class with a horizontal double
 line but you don't want to spoil the RDoc output:

 1. This provides clear visual start to class and will keep the comment in the
    RDoc output.

#--== ClassName =============================================================#
#++
#  Provide any comments that will help others understand the class.
#  You can either consistently leave one or two spaces after the hash.
#  The 2nd line must be the same as 1st or else it is treated as a verbatim.
class ClassName

 2. A slightly more compact version of the above style.

#--== ClassName =============================================================#
#++you can't have a space after the ++ or else it is treated as verbatim text.
#You also can't have a space after the # because otherwise it includes the '#'
#in the RDoc html output. This might fell a bit squashed or to compact.
class ClassName

 3. When you only have a single comment line this is the style to use since it
    is not as compact as above and yet does not waste an entire line for '#++'

#--== ClassName =============================================================#
#++ When only writing a single comment you can leave a space after '++'.
class ClassName


 4. This style simply used for highlighting start of class since no RDoc
    comment will be produced.

#--== ClassName =============================================================#
class ClassName


 5. Shorter double lines can also be used to suit ones own style (this means
    the class will standout less when reading the source code). This can be
    used with any of the above styles. [Not so sure of the value of this style
    although when using colours in your editor it can be visually distinct
    enough to be worth adding]

#--== ClassName ====#
class ClassName


+------------------+
| METHOD COMMENTS: |
+------------------+

 Method comments are really the same as class comments except that you only
 use '#-- ' instead of '#--== ':

 1.

  #-- MethodName ------------------------------------------------------------#
  #++
  #  Same issues as explained above in class comments
  def MethodName

 2.

  #-- MethodName ------------------------------------------------------------#
  #++ Short comment that helps readers understand method functionality
  def MethodName

 3. Short line as

  #-- MethodName --#
  #++ Short comment that helps readers understand method functionality
  def MethodName



+-------------+
| VARIATIONS: |
+-------------+

 1. leaving a blank line between comment block and class or def line:

#--== ClassName =============================================================#
#++
#  comments lots and lots of useful comments and lots of useful comments
#  and lots of useful comments and lots of useful comments and lots of useful

class ClassName


 OR


  #-- MethodName ------------------------------------------------------------#
  #++ Short comment that helps readers understand method functionality

  def MethodName


+-----------------------+
| OTHER COMMENT STYLES: |
+-----------------------+

 1. Want to highlight something interesting or indicate something specific
    * all caps to hight
    * starts with '##' so that it isn't confused with methods or classes and
      the #-- stop comment tag isn't triggered.

    ##-- INDICATES LOGICAL SECTION --##

 2. box up the comment for real emphasis

    ##-------------------##
    ## IMPORTANT TO NOTE ##
    ##-------------------##

 2. Normal comments can be made using # or ## as per usual coding comment rules


+------------+
| QUESTIONS: |
+------------+

 1. The lines should end at char 78 this gives you at least one indent to play
    with without having to delete any '-' or '='

 2. does '#---- ClassName =====' look better than the style above?

+-------------------+
| COMPLETE EXAMPLE: |
+-------------------+

#--== OptionHandler =========================================================#
#++ Deal with *command* line options specific to this module

class OptionHandler
  #-- initialize ------------------------------------------------------------#
  #++ usually called with the ARGV from the invocation

  def initialize(argv)
    ##-- DEFAULT OPTION VALUES --##
    $opts           = OpenStruct.new
    $opts.operator  = ENV['SUDO_USER'] || ENV['USER'] || Process.uid
   
    $opts.fix         = false # when running audit don't make changes by default
    $opts.verbose     = false

    $opts.env         = 'prod'
    $opts.config_file = 'athena_config.yml'

    begin
      options = parse_options!(argv)
    rescue OptionParser::ParseError => ex
      puts "Error: #{ex}"
      RDoc::usage(1,"Usage") # exit with error code 1
    end

    ##-- CONFIGURATION --##
    cfile = YAML.load_file($opts.config_file)

    # multiple environments can be defined in the config file, load the one
    # that is defined by the option variable defined on CL.
    $conf = OpenStruct.new(cfile[$opts.env])
  end

  #-- parse_options!---------------------------------------------------------#
  #++
  #  Use the OptionParser object to handle all command line options. It
  #  modifies the Array passed to it, removing all options while leaving the
  #  remaining arguments to be processed separately. Usually called with ARGV.

  def parse_options!(argv)

    options = OptionParser.new do |op|
      op.on("-c", "--config YAML_FILE") {|c| $opts.config_file = c }
      op.on("-e", "--env ENV")          {|e| $opts.env         = e }
      op.on("-f", "--fix")              {|f| $opts.fix         = f }
      op.on("-v", "--[no-]verbose")     {|v| $opts.verbose     = v }

      op.on("-h", "--help")     {RDoc::usage(0,"Usage")}   # RDoc use & exit(0)
      op.on("-V", "--version")  {RDoc::usage(0,"Version")} # RDoc ver & exit(0)
    end

    options.parse!(argv)
  end
end

# vim: syntax=ruby

Rdoc::usage

You want to display the usage info for your code both in the comments at the top of the source file and have it printed out when given the -h or –help command line option. The problem with this is that it is hard to keep the two in sync - one is embedded in the code the other is just a comment. NOT ANY MORE. RDoc::usage parses the comments at the top of the file and uses that for printing the usage message:

#!/usr/bin/ruby

#==Usage
#  usage: test.rb

require 'rubygems'
require 'rdoc/usage'

RDoc::usage

There are some problems though:

1. Stub /bin files. If you want to use a ruby gem format of putting your bin files in /bin and the bulk of your code in /lib then there is a problem because RDoc::usage on only looks at the comments from the first file (which would be the stub bin file)