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.
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?
____________________
Racket Users list:
http://lists.racket-lang.org/users
