From: Massimiliano Mirra <list@...>
Date: 2002-01-05T01:59:37+09:00
Subject: [ruby-talk:30225] Docstrings

I still can't see how and where they can do better than a tool like
rdoc, but everyone keeps mentioning them, so here is something simple
and hopefully useful.

I'm sure a lot of optimizations can be applied (checks for mistakes
and non-existing methods, argument lists etc.) but I'll leave it to
who has any use for it.

Documentation for built-in classes could be done like for Array below
and included in a `documentation.rb' file.  Then run irb, require
'documentation', and here are your docstrings.

HTH

Massimiliano


module Documentable
  class << self
    def append_features(base_class)
      base_class.class_eval do
	@@docs = {}
      end

      def base_class.doc(method, docstring = nil)
	if docstring 
	  @@docs[method] = docstring
	else
	  @@docs[method]
	end
      end
    end
  end
end


if $0 == __FILE__ 
  class Foo
    include Documentable

    def bar
    end
    doc :bar, "Very useful?"


    def sample
    end 
    doc :sample, "Not for me."

    def long
    end
    doc :long, <<EOF
But using	
multiple lines
could be really nice
EOF
  end

  f = Foo.new
  puts Foo.doc :bar
  puts Foo.doc :sample
  puts Foo.doc :long



  class Array
    include Documentable
  end

  Array.doc :collect, <<EOF
---------------------------------------------------------- Array#collect
     arr.collect {| obj | block }  -> anArray
------------------------------------------------------------------------
     Returns a new array by invoking block once for every element,
     passing each element as a parameter to block. The result of block
     is used as the given element in the new array. See also
     Array#collect!.
        a = [ "a", "b", "c", "d" ]
        a.collect {|x| x + "!" }   #=> ["a!", "b!", "c!", "d!"]
        a                          #=> ["a", "b", "c", "d"]
EOF

  puts Array.doc :collect
end