From: sera@... (Francis Hwang)
Date: 2003-08-11T22:16:53+09:00
Subject: Re: Ruby docstrings

A related issue is that if you use method_missing to dispatch method
calls, there's almost no standard way for a parser to figure out what
sorts of methods you're intending to define. I run into this a lot
because my pet project Lafcadio uses method_missing a lot to let
objects serve as facades for collections of subsystems, and I just
finished writing RDoc comments for everything. When it came down to
the methods handled through method_missing, I had to write class
comments because there's no individual method definition for RDoc to
parse.

All of this is not to complain about RDoc, which is a fantastic tool.
In some ways, it's nice to have this sort of problem. For a language
like Java you don't run into this problem because reflection is so
bloody painful in that language. Ruby lets you be more flexible and
clever with method names, but the downside of that is that it raises
the bar for programs (like RDoc) whose functionality depends on
understanding that code.

Francis

William Webber <wew@williamwebber.com> wrote in message news:<20030811020227.GA2043@elysium.domus.prv>...
> 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