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

I will second the idea behind this request. (I thought I had to use dynamic-require's second argument in the summer, and after studying it for quite a while, i was happy to figure out a way around it.) 


On Sep 14, 2012, at 3:17 PM, Carl Eastlund wrote:

> 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
> _________________________
> Racket Developers list:
> http://lists.racket-lang.org/dev