From: Phrogz <gavin@...>
Date: 2007-06-16T03:00:04+09:00
Subject: Re: Abstract interfaces as a means of documentation

On Jun 15, 6:57 am, Eli Bendersky <eli...@gmail.com> wrote:
[snip]
> And now I want to document what these methods do (with a block comment
> describing the arguments and return values, presenting examples,
> etc.), and I want the documentation to be reflected in the RDoc of my
> code. What are my options ? As I see it, several:
>
> 1) Duplicate the same documentation for each class.
> - This is hardly feasible for large class-families and violates DRY.
>
> 2) Don't document. Give the methods and arguments descriptive names,
> and write test cases that show how to use them.
>
> 3) Create a "dummy" abstract class that doesn't really do anything
> (and is never instantiated), something like:

4) Create a Module and document the method in the module, and then
include that module in each class. Similar to your abstract class, but
solves the problems of instantiation, and allows you to mix in methods
along various axes.

module JumpingClimbingPlayer
  # docs here
  def jump
    raise "You should implement this per player"
    # or maybe implement the common technique
  end

  # same for climb
end

class FooTypePlayer
  include JumpingClimbingPlayer
  def jump
    # specific implementation here
  end
end