From: William Webber <wew@...>
Date: 2003-08-11T10:49:00+09:00
Subject: Ruby docstrings

Hi all!

I'm currently engaged in RDoc'ing the stdlib as part of the ruby-doc
project.  This has made me very much aware of how the dynamic nature
of Ruby makes a documentation system not integrated into the language
itself very difficult to develop, what with aliases, class << self,
instance_eval and module_eval etc..  While Dave Thomas has been very
helpful with extending RDoc to handle various different combinations
of the above, this ultimately amounts to writing a second Ruby parser
just to parse out documentation--and there are limits to how far any
sane person is prepared to pursue this approach.

Why doesn't Ruby adopt the docstring convention used in the Scheme and
Lisp worlds, and also by Python?  For those unfamiliar with this, a
"docstring" is a standalone string constituting the first
statement/sexp of a function or (in Python) class definition.  The
runtime generally has hooks to extract and display this documentation.
For instance, in guile I can do:

  (define (foo-cons bar)
     "Cons the string 'foo' onto the argument"
     (cons "foo" bar))

and then in the interpreter:

  guile> (procedure-documentation foo-cons)
  "Cons the string 'foo' onto the argument"
  guile>

Then hooks could be added to the Ruby interpreter to parse, store and
extract docstrings.  RDoc and other documentation systems would then
just have to load up any Ruby files they wanted to document inside the
Ruby interpreter, and use it to extract the documentation from classes
and methods; there would be no need to develop and maintain a separate
Ruby parser for documentation purposes.  ri/rj and other command-line
documentation utilities could operate similarly, rather than having to
maintain a dump of documentation that is separate from the actual
libraries.  IDEs and even irb would have easy built-in documentation
facilities.  Best of all, the most exotic and inscrutable techniques
for defining new methods, currently inscrutable to RDoc and likely
always to remain so, would under this system still be capable of
producing documentation.

Is there a reason why Ruby hasn't taken this approach?  Would it be a
good approach to take?

William