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