From: Harry Ohlsen <harryo@...>
Date: 2002-09-01T03:44:39+09:00
Subject: Re: suggestions to the Ruby community

> My boss, to give you an example, nearly pulled out his hair trying to
> figure out how to use DBI, because he expected documentation to be
> someplace obvious, like ./doc/README, not in lib/dbi/doc/DBI_SPEC. My
> point being that while, yes, some external packages are simply devoid
> of documentation, in many cases what you're seeing is not frustration
> at the lack of documentation, but at the lack of consistency with
> regard to its location, format and presentation.

This is just a thought, but, Python has a standard (discussed in this forum 
some time back) that if there's a string before the first executable line of 
code in a class then it's intended to contain some documentation about that 
class.

For example (recast as Ruby, because I can't remember enough Python) ...

   class Fred
      """class Fred is just an example"""

      def initialize
          # The constructor for Fred
      end
   end

In Python, one can get at these strings by doing things like ...

   print Fred.__doc__

(Yes, I hate all those undescores, too !!)

To allow Ruby authors some freedom in where they put their documentation, 
could we not define a convention that a class has a "doc" method (personally, 
I'd prefer to spell it out and say "documentation", but I'm sure others would 
prefer the brevity of "doc") that returns a String?

Then, each author could code that method any way they like.  Eg, it could just 
return a constant string, a la Python ...

   class Fred
      def doc
         "Class Fred is just an example"
      end

     def initialize
        # ...
     end
   end

The string returned could, for example, be a URL where the user can find the 
documentation. Or doc() could do something more complex, like return the 
contents of a file ...

   class Fred
      def doc
         File.new("some/path/Fred.doc").readlines.flatten
      end
   end

We could have Object define some kind of generic version that just explains 
that this particular entity doesn't seem to have its own documentation, 
giving some suggestions on where to try looking for it.

I'm sure other, more Ruby-fluent people will think of ways to make this more 
usable.  I'm just throwing this into the mix, to see if it sparks any cool 
ideas.

For example, we could have a standard tool, similar to ri, that when given the 
name of a class/module, would go off and call doc() and print what was 
returned.  If doc() wasn't defined, it could pass the request on to ri, or go 
looking for some rd or rdoc information.

For that matter, it could *both* print what doc() returns *and* call ri to see 
what's there.

Anyway, just an idea.

Harry O.