gistfile1.rb

#!/usr/bin/env ruby

require "with_args" # TBA

class User
  with_args String,
  def name=(name)
    @name = name
  end

  with_args Hash,
  def to_json(options = {})
    @attributes.to_json(options)
  end

  with_args "Send an invite to this user", String,
  def invite!(email)
    UserMailer.invite(self, email).deliver
  end

  with_args "Check if this user has the same name as another", :name,
  def eql?(user)
    name == user.name
  end

  with_args "Do something with", String, "and optional", Hash,
  def something(string, options = {})
    
  end
end

u = User.new
u.name = 1         # WithArgs::TypeError -- Expected a String
u.eql?(Object.new) # WithArgs::TypeError -- Object does not respond to `name'

# Annocations for free
User.annotations #=>
  {
    "name="     => "name=(String)",
    "to_json"   => "to_json(Hash)",
    "invite!"   => "Send an invite to this user String",
    "eql?"      => "Check if this user has the same name as another",
    "something" => "Do something with String and optional Hash"
  }

I'd very much enjoy seeing your implementation of WithArgs :) I started doing something similar to auto-document public-facing API methods.