On Fri, Feb 6, 2015 at 5:16 PM, Matthew Butterick <m...@mbtype.com> wrote: > > On Oct 29, 2014, at 10:39 AM, Sam Tobin-Hochstadt <sa...@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 ____________________ Racket Users list: http://lists.racket-lang.org/users
