From: dblack@...
Date: 2003-08-11T21:36:51+09:00
Subject: Re: Ruby docstrings

Hi --

On Mon, 11 Aug 2003, William Webber wrote:

> On Mon, Aug 11, 2003 at 12:14:44PM +0900, Dave Thomas wrote:
> > 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?
>
> Well, the Ruby interpreter would have to load the files, so yes,
> the top-level code in each file would get executed.  Most of
> this code will just be defining classes, methods, and constants; I'm
> assuming that the Ruby interpreter does some sort of parsing of these
> on load, and could extract docstrings?

There's a big difference, though, between this and the kind of thing
that, say, Emacs Lisp or Smalltalk do (based on my use of the former
and a few years of hearing people talk in my presence about the
latter).  In those environments, you've got a running image, and the
docstrings help you query it while it's running (i.e., certain methods
or functions exist in memory, and you're querying the memory).  In the
case of Ruby, we're talking about creating documentation from a bunch
of files.  Actually executing those files (as opposed to just parsing
them for documentation) has very different implications.

> For more dynamic method definitions like the following (from date.rb):

[... date example ...]

How about this:

  case SOME_CONSTANT
  when x
    def quack .... end
  when y
    def meow .... end
  end

where SOME_CONSTANT might be configurable at run-time, and so on.
Again, this would be different if you were working inside a run-time
image: there would be an exact and natural correspondence between the
methods that got defined, and those for which you could retrieve the
docstrings.  But if you've just got the above sitting in a file, and
you're going to execute it and terminate, it's unclear how the
documentation would be produced based on the execution alone.

> (BTW, I think the above is an example of why docstrings are attractive
> in Ruby: we're directly leveraging the language and its ability to
> eval at load/run time to dynamically generate documentation.)

I'd quibble perhaps with 'directly'; there's nothing indirect about
writing a program in Ruby that performs operations on a file, even if
that file happens to contain Ruby code and you don't happen to execute
it :-)

> It's true that some files might expect to be loaded in only a
> particular context, and might misbehave if they aren't.  I can
> imagine a command-line-argument parsing utility or a cgi library being
> written this way (I don't know if the Ruby stdlib ones actually are).
> But would any reasonable library actually cause damage if loaded at
> the incorrect time?  And couldn't we just tell the interpreter to
> ignore top-level errors as much as possible, and continue looking for
> docstrings?  Besides, isn't it in general bad style to do much more
> than definitions during a file load, particularly for a library?

I think this kind of modification of the interpreter starts to sound a
lot like the dedicated documentation parser you wanted to avoid :-)
I'm hoping Dave will follow up with some juicy examples of dangerous
situations.  But in general, I think the run-time generation of
documentation probably makes more sense in cases (like Smalltalk)
where you're actually working inside a running image over a period of
time, not just executing a program.


David

-- 
David Alan Black
home: dblack@superlink.net
work: blackdav@shu.edu
Web:  http://pirate.shu.edu/~blackdav