[racket-dev] self-documenting feature
Python apparently has a feature where you essentially put the contract/purpose in the text of a function, and when you type the function's name, it prints out that documentation. (It sounds like the docstrings of Common Lisp.) This came up on day 1, minute 15 of the TSRJ workshop. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
Yes, when I taught "HtDP" in Python two years ago, this feature was handy. It provide a more convenient way for recalling/looking up contract/purpose statements right in the REPL than opening a search in a browser. If I remember correctly, I think the IDE might have also done something smart with these, like providing a popup hint with the function doc (or at least the first line) when you typed the function name while editing a file. Here's a quick interaction with the Python shell in IDLE: >>> def f(x): '''this is the first line this is the second line of the doc and so on''' return 3+x >>>f( (at this point a text hint pops up with the following contents: |- | (x) | this is the first line |- So, it worked very well with the design recipe if you put the contract as the first line in the comment. Then for more detail, you use "help": >>> help(f) Help on function f in module __main__: f(x) this is the first line of the doc and so on --- nadeem On Jul 19, 2010, at 10:16 AM, Shriram Krishnamurthi wrote: > Python apparently has a feature where you essentially put the > contract/purpose in the text of a function, and when you type the > function's name, it prints out that documentation. (It sounds like > the docstrings of Common Lisp.) > > This came up on day 1, minute 15 of the TSRJ workshop. > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
While I have always liked doc strings in Lisps -- and koodos to Python for copying another feature from Lisp -- is it as critical to HtDP programming as built-in check-expect with coverage? (No but I think having it would be nice.) Do ask the person who asked whether Python has coverage now. -- Matthias On Jul 19, 2010, at 10:16 AM, Shriram Krishnamurthi wrote: > Python apparently has a feature where you essentially put the > contract/purpose in the text of a function, and when you type the > function's name, it prints out that documentation. (It sounds like > the docstrings of Common Lisp.) > > This came up on day 1, minute 15 of the TSRJ workshop. > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
Sure, but if we have the manpower/energy for this, then it would be nice to have, no? (We'd probably do something syntactically and not via runtime values, but the essential idea seems like it would carry over.) Robby On Mon, Jul 19, 2010 at 11:05 AM, Matthias Felleisen wrote: > > While I have always liked doc strings in Lisps -- and koodos to Python for > copying another feature from Lisp -- is it as critical to HtDP programming as > built-in check-expect with coverage? (No but I think having it would be > nice.) Do ask the person who asked whether Python has coverage now. -- > Matthias > > > > On Jul 19, 2010, at 10:16 AM, Shriram Krishnamurthi wrote: > >> Python apparently has a feature where you essentially put the >> contract/purpose in the text of a function, and when you type the >> function's name, it prints out that documentation. (It sounds like >> the docstrings of Common Lisp.) >> >> This came up on day 1, minute 15 of the TSRJ workshop. >> _ >> For list-related administrative tasks: >> http://lists.racket-lang.org/listinfo/dev > > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
> Do ask the person who asked whether Python has coverage now. -- Matthias Aspirin vs vitamins. Shriram _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
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. " _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
And which is which :-) On Jul 19, 2010, at 1:24 PM, Shriram Krishnamurthi wrote: >> Do ask the person who asked whether Python has coverage now. -- Matthias > > Aspirin vs vitamins. > > Shriram _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
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. > " _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
>> Do ask the person who asked whether Python has coverage now. -- Matthias Maybe not packaged for beginners, but it is doable... http://pypi.python.org/pypi/coverage/2.85 http://nedbatchelder.com/code/coverage/ _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
That's the question. Packaged for beginners; always there, never to ask for. On Jul 19, 2010, at 4:55 PM, Nadeem Abdul Hamid wrote: >>> Do ask the person who asked whether Python has coverage now. -- Matthias > > Maybe not packaged for beginners, but it is doable... > http://pypi.python.org/pypi/coverage/2.85 > http://nedbatchelder.com/code/coverage/ > > > > > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
Yes, but Racket docstrings aren't even there at all (yet :))... On Jul 19, 2010, at 4:58 PM, Matthias Felleisen wrote: > > That's the question. Packaged for beginners; always there, never to ask for. > > > On Jul 19, 2010, at 4:55 PM, Nadeem Abdul Hamid wrote: > Do ask the person who asked whether Python has coverage now. -- Matthias >> >> Maybe not packaged for beginners, but it is doable... >> http://pypi.python.org/pypi/coverage/2.85 >> http://nedbatchelder.com/code/coverage/ >> >> >> >> >> > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
This is a pointless exchange that misses the reason for its initiation. Attendee: "Here's a nice feature that I find awfully useful. How do I get it in DrRacket?" Us: "Oh yeah? And can your beloved language do X?" Shriram On Mon, Jul 19, 2010 at 4:58 PM, Matthias Felleisen wrote: > > That's the question. Packaged for beginners; always there, never to ask for. > > > On Jul 19, 2010, at 4:55 PM, Nadeem Abdul Hamid wrote: > Do ask the person who asked whether Python has coverage now. -- Matthias >> >> Maybe not packaged for beginners, but it is doable... >> http://pypi.python.org/pypi/coverage/2.85 >> http://nedbatchelder.com/code/coverage/ >> >> >> >> >> > > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
Robby Findler wrote at 07/19/2010 12:31 PM: Sure, but if we have the manpower/energy for this, then it would be nice to have, no? I've been wanting something docstring- or javadoc-like for Scheme and Racket since forever. I have had my own kludges for this since forever, but neither myself nor anyone has had time to do it right. If someone does this right, and it's pleasant to use, I will happily convert all my code over to it and shoot my old kludges in the head. -- http://www.neilvandyke.org/ _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] self-documenting feature
You probably already know about this, but proc-doc is the closest we have at the moment. Robby On Mon, Jul 19, 2010 at 7:04 PM, Neil Van Dyke wrote: > Robby Findler wrote at 07/19/2010 12:31 PM: >> >> Sure, but if we have the manpower/energy for this, then it would be nice >> to have, no? >> > > I've been wanting something docstring- or javadoc-like for Scheme and Racket > since forever. > > I have had my own kludges for this since forever, but neither myself nor > anyone has had time to do it right. > > If someone does this right, and it's pleasant to use, I will happily convert > all my code over to it and shoot my old kludges in the head. > > -- > http://www.neilvandyke.org/ > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev > _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
