Ruby docstrings

[William Webber]

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

 

[Dave Thomas]

William Webber wrote:
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?

But surely those method definitions would only be available if you
actually executed the code? Wouldn't that be fairly dangerous?


Dave

 

[Francis Hwang]

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

 

[Gavin Sinclair]

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.

I imagine that this is the only kind of documentation that would make
sense in that scenario.

Classes that are documented "Supports all the methods of Foo::Bar, but
does *this* in addition" are well documented, IMO.

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.

Gavin

 

[Joel VanderWerf]

Would it help if I added a facility to RDoc to let you tell it about
methods that it can't find for itself, perhaps something like:


# Dynamically constructed method that handles
# SOAP requests from the washing machine.

# :def: dynamic_method(arg1, arg2)

You have my vote