[racket-dev] self-documenting feature

From: Matthias Felleisen (matthias at ccs.neu.edu)
Date: Mon Jul 19 14:38:30 EDT 2010

That's totally different from what Shriram described. 

On Jul 19, 2010, at 1:53 PM, Guillaume Marceau wrote:

> During
> 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?
> overlay.
> "
> 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.