> I like docstrings.  I like being able to type "help(foo)" in python and
> get help on the foo method.

I agree that ruby lacks something like a
method.desc
functions
which would be quite useful in irb.
http://www.ruby-forum.com/topic/178393#781323
lists a few thoughts on it.

Benefits of docstrings: you can get 'built in' realtime documentation.
 I *hate* having to go to a new window and run ri and wait for 30
seconds to get help on a function.
You can "kind of" fake it using fastri and some hacks to irb to patch
into it.  But it's not default.
Other benefit: you can have documentation for dynamic methods.
Ex: there is no way currently to know just what methods will be
defined on call to method_missing. So ri lacks in that way.

That being said, however, as a poster mentioned, in the above link,
docstrings and rubydoc style comments are really about the same.

Another hack at it is the sourceref style [1], which is possible in
1.9 now that we have Proc#source_location.

One drawback to it is that you are kind of limited in how verbose you
can be since if you have comments that are too long it distances the
method name from the code.
So the question is...is what we have enough?

If not one option would be to rewrite the ri format so that lookup is
fast.  Another would be to perhaps leverage something like sourceref
for quick ri lookup.

My current leaning is to just create an "irb method lookup" gem that
leverages [2] and sourceref and proc#parameters, and starts its own
fastri process if one isn't running [in a new thread].
Thoughts?
-=r

[1] http://sites.google.com/site/brentsrubypatches/
[2] http://eigenclass.org/hiki/irb+ri+completion

> I don't like docstrings.  They don't let you write documentation for
> variables -- only modules, classes, and methods.  We're using epydoc,
> and it has a special syntax for elements of the program that python
> doesn't handle.
>
> I like restructed text.  It means that the documentation is readable in
> a text editor, much like having wiki formatting inside my code.
>
> I don't like restructed text.  The syntax and rules are complex, and
> sometimes it's hard to remember what sort of syntax I'm supposed to use.
> If I get it wrong, there's no compile error; it just doesn't show up
> correctly in the documentation.
>
> I know these things aren't quite what you were getting at, but I
> thought I'd chime in anyway.
>
> Paul