From: Gavin Sinclair <gsinclair@...>
Date: 2004-08-19T12:53:20+09:00
Subject: Re: Documenting a class interface when there are no types in the method signature

Nicolai wrote, in part:
> Many times I have run into some library where I was simply asking myself
> "what exactly do I have to put into these parameters to get the method
> to do what I want?" More specifically, I had this problem in parts of
> the REXML library.
>
> And from the other perspective, what is the Ruby Way (tm) to document
> methods to users of your API/framework (or simply your class)?

Regarding your example of initialize, I tend to do this.

    #
    # Detailed usage example...
    #
  class Foo
      # (String) blah blah blah
    attr_reader :name
      # (Hash: Symbol -> Set) blah blah blah
    attr_reader :categories
      # (IO-like: responds to ...) blah blah blah
    attr_reader :output

    def initialize(name, output)
      ...
    end

    def add_category(id, thing)
      @categories[id] ||= Set.new
      @categories[id] << thing
    end
  end


My point: if you provide a decent usage example, then people can read that
and see what they need to do to work with the class.  Give some nitty
gritty on the attributes, because they are usually key to understanding
the class.  Then the methods will often not need documenting at all.

Cheers,
Gavin