[racket-dev] self-documenting feature

From: Guillaume Marceau (gmarceau at gmail.com)
Date: Mon Jul 19 13:53:46 EDT 2010

There is good support from the interviews for having dynamic
documentation in DrRacket would help quite a bit. Two out of the four
students I interview requested the feature.

Here are some relevant inteview excepts.

Student #1:
Maybe a tiny example, or something, that follows the contract and
purpose of AND, might help. Because a lot of the time when I was doing
these I found myself not remembering the contract and purpose for
little things like this, like AND. It can take in multiple things. But
the real thing I forgot is if they want things to the end.  The
problem is that they all have to be inside the parentheses.
G, you're forgetting the contract and purpose of different functions?
S, of course that happens a lot. CONS, LIST, APPEND, STRING-APPEND,
all things we use, I forget what it takes in. Sometime I think of
using SYMBOL? instead of SYMBOL=? and I have to take that extra second
just to think after I've noticed I have an error. Which one do I use,
SYMBOL?, or SYMBOL=? because they are relatively the same thing. They
both produce Boolean, but one says this equals to the other. Having at
least a little example, or the contract, or the purpose, the contract
probably would help a lot. But that would be a lot of work to, but it
would definitely help.

I remember the contracts, the documentation of the contracts, and
having to look it up. What does AND take in? Or what is APPEND. Or
what about MIN vs MAX? Which takes in which? The x/y, I forget?

Student #2:
Random idea, but perhaps something that could be helpful... maybe
under the error if you could somehow put an example of a define struc
t... just something to show define-struct is define-struct open
parenthesis something something
G, some kind of syntax reminder
S, yeah. Because there was probably my hardest thing, trying to learn
the language? like when you add five and seven, its (+ 5 7)  not
(5+7)?  example would probably be really useful.

and later during the interview:
For example define-struct, ever since we started using it a lot, it
was just something that I knew how to use because we used it almost
everyday in class. But for something like format, or filter, I would
just touched on in one lecture, then we would have to use it in
special circumstances, an example in the error message would be
awesome. It would be a very good reminder.

Posted on the dev mailing list.