[racket-dev] self-documenting feature

From: Nadeem Abdul Hamid (nadeem at acm.org)
Date: Mon Jul 19 10:29:41 EDT 2010

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



Posted on the dev mailing list.