[racket] Typed Racket frustration

On Fri, Feb 6, 2015 at 5:16 PM, Matthew Butterick <mb at mbtype.com> wrote:
>
> 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.

Can you say more about what the best workflow for you would be here?
Should this information appear in the blue boxes that DrRacket shows,
or in a tooltip, or somewhere else? Or do you want to have it listed
in a separate document that you read in the browser? Or something else
entirely?

> 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?

I'm not sure what you're imagining the "instantiation-arg-spec" would
look like. If we add documentation with the types of standard library
functions, then I think the most useful thing to present is the actual
type (or perhaps a simplified version in some cases where the type is
very large). In particular, I don't think that we could describe how
to instantiate polymorphic types better than by giving the type.

There are also issues we'll need to address about how to have multiple
entries in the documentation for a single function, and how to combine
that information in what DrRacket shows, but I'm confident we can
figure those out.

Sam