[racket] Typed Racket frustration

On Oct 29, 2014, at 10:39 AM, Sam Tobin-Hochstadt <samth at cs.indiana.edu> wrote:

> As for documenting this, the types, which you can print at the REPL,
> are the best documentation. Just recently, Asumu added tooltips so
> you'll be able to see the type of `hash` online in DrRacket. I don't
> think repeating the types for every export of `racket` in the
> documentation would be helpful, especially in cases where they're
> quite complicated.

As I've gotten farther into porting code into TR, one of the recurring tasks that sends me looking for documentation is instantiating polymorphic functions into appropriate type-specific forms using `(inst proc args ...)`. 

Why? Because each polymorphic `proc` has its own special list of instantiation `args ...` that sometimes correspond in an obvious way to the regular arguments, sometimes not. 

And yes, while you can see this info in the REPL, sometimes the instantiation spec is self-explanatory (e.g. `vector`):

- : (All (a) (-> a * (Vectorof a)))

And sometimes not (e.g. `hash-ref`):

- : (All (a b c)
      (case->
       (-> (HashTable a b) a b)
       (-> (HashTable a b) a False (U False b))
       (-> (HashTable a b) a (-> c) (U b c))
       (->* (HashTableTop a) (False) Any)
       (-> HashTableTop a (-> c) Any)))

Supposing I wanted to add this documentation to TR (and I do), what would the best way of setting it up? For instance, I'm wondering if it would make sense to:

1) create an enhanced version of `defproc` that takes an instantiation-arg-spec in addition to the standard arg-spec?

2) create `definstproc` that only handles the instantiation-arg-spec, and links back to the standard `defproc` documentation?

3) Something else?