From: Chad Fowler <chadfowler@...>
Date: 2003-01-16T03:52:44+09:00
Subject: Re: Doc Strings?

Dossy wrote:

>Or, try this:
>
>class Module
>  def __doc__(x = nil)
>    if not x.nil?
>      @@doc = x
>    end
>    @@doc
>  end
>end
>
>class Foo
>  __doc__ "some docs for class Foo"
>  
>  # rest of Foo stuff here
>end
>
>f = Foo.new
>f.class.__doc__     # => "some docs for class Foo"
>
>Foo.__doc__         # => "some docs for class Foo"
>
>
>I think this was posted to the ML a few months ago.
>
>-- Dossy
>
>  
>
I was just thinking about how you could use __doc__ inside a method call 
and dynamically add doc information to the symbol representing the 
method from which you call it.  This brings me to a question:  How do 
you find out where a method is called from?  I used to do this in Java 
through some nasty stack trace hacks (throw an exception and 
capture/parse the stack trace string).  I seem to remember when I was 
first learning Ruby a couple of years ago that there is a better way to 
do this in Ruby, but I can't seem to specifically remember what it was.

Anyone know?

This way, you could potentially extend this __doc__ idea to work like this:

class Symbol
  attr_accessor :doc
end

def some_method
  __doc__ "This is what some_method does...." #=> doc string would now 
be accessible via :some_method.doc
end

class Test
  __doc__ "Documentation for class" #=> Now, :Test.doc returns the doc 
string
end

...and so on.

I'm not sure how useful any of this is (never used the doc string 
concept, personally), but now I want to know how to do it.  Hopefully 
I'm just forgetting something obvious.

Chad