[racket-dev] Documentation for dynamic-require and related terms is confusing.

I just tried to figure out what the second argument of dynamic-require does
when it's not a symbol, for the nth time.  First of all, the current
interface -- 0, #false, and (void) as tokens for three rather arbitrary
modes of operation -- leaves much to be desired.  These other modes should
probably be other functions, or one other function with flags that are more
mnemonic.

Second, the documentation of these modes is based on the technical terms
"instantiate", "visit", and "available", which I find incredibly arcane.
Even now that I have looked them up and know what they mean (I _think_), I
don't know why these particular words were chosen for the concepts they
represent.

To the best of my understanding, "instantiate" means "allocate space for,
and run, the relative-phase 0 content of a module"; "visit" means the same
thing at relative-phase 1.  Neither the terms nor their documented
definitions actually indicate this close relationship; I had to puzzle it
out to realize they are almost the same thing, essentially differing only
by add1.  I would much prefer related terms, or even just one term used
with a phase number.  Otherwise I'm running around with two words for what
seems to be just one concept.  I'm also confused that there is no term for
running module contents at higher phases.

The term "available" appears to mean "queued up for on-demand
instantiation".  Could we perhaps just say "lazily instantiated" here or
something?  Again, the word "available" here doesn't really suggest what's
going on to me.  Especially because to a user, the module doesn't actually
become any more available than it was; it's only to the runtime
implementation that the module suddenly becomes "available".  And I don't
think Matthew's C code reads the documentation very often.  (Though that
would be impressive!)

Of course, if I've interpreted these terms incorrectly, there's a further
problem with either the explanation or my reading comprehension.

I can certainly understand how the documentation got to this state.  The
module system is incredibly complicated, and at the outset I wouldn't know
what to name anything, either.  And I would imagine dynamic-require's
interface has evolved over time.  Now that we've had it a while, though, I
think we can do a lot to improve the clarity of these features.  I hope
someone who understands them better than I do can take a stab at it.

Carl Eastlund
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/dev/archive/attachments/20120914/8849cde7/attachment.html>