[racket] Exploratory programming?

From: Ryan Culpepper (ryanc at ccs.neu.edu)
Date: Wed Dec 1 23:12:43 EST 2010

My $0.02: Most of the time when I hit the docs for a function, all of 
the information I need is in the blue box: usually I'm looking at the 
contracts, but the argument labels help me when I forget the order 
things go in. I'd be happy with a tool that showed just the contents of 
the blue boxes, formatted as text.

At the repl, (blue-box id)---names changed to protect the 
unimplemented---should print out the header and contract information 
associated with id. Perhaps (blue-box "id") should print out the 
blue-box information and require line for everything matching "id" 
exactly. And other search options as needed.

In DrRacket, there should be a way of getting the same information in an 
on-demand panel (like the find/replace panel or 
error-during-check-syntax panel). It must be available without running 
Check Syntax, however, through some combination of search, caching, 
heuristics, and mind-reading.

It would be great if it were also available in emacs/quack etc.


Eli Barzilay wrote:
> Two hours ago, Greg Hendershott wrote:
>>> I wonder whether help could display contracts if the module use
>>> provide/contract to export f.
>> I like this idea.
> I don't think that combining all of these is right.  To go over the
> various pieces there are three that are very different:
> 1. (help id) -- opens a browser window on the documentation for `id'
> 2. there's the description of which module some identifier is coming
>    from, where was it defined, and what name was it defined as (some
>    of it is what check-syntax shows, and also what my interactive
>    ,describe command does)
> 3. and there's the description of a value
> The first is very different from the other two -- I often want to see
> #2 but don't want a browser window, or if I want to look at the docs
> then I don't need #2.  So lumping them together doesn't sound right.
> So it might make a little more sense to bundle all of the light-weight
> quick output features, like #2 and #3, but they're very different from
> each other -- #2 is syntactic and #3 uses the value.  So merging them
> into a single facility can be confusing.
> [Re python, my guess was that it's more limited in having no
> syntactic-level tool -- and I do see that things like help(+) or
> help(if) don't work.  And BTW, after only a few experiments, python's
> `help' looks like a mess: help(3) is the same as help(int), help("3")
> does some search, etc etc.  Hardly looks like a good tool to
> imitate...]
>> Maybe go a step further and allow per-parameter doc-string-ettes?
>> Because seeing
>>   get-pure-port: (url? (listof string?) . -> . input-port?)
>> Might still be too opaque. "What is this (listof string?) you speak
>> of?", sayeth the aspiring Racketeer on the PLimoTh PLanTation.
>> Whereas if contracts could have optional doc-string-ettes:
>>   (url? ["URL"] (listof string?) ["headers"] . -> . input-port?)
>> Then help could display something very close indeed to the shaded
>> blue box summary on docs.racket.org.
> Ideally, the documentation could be rendered in some way that could be
> displayed in text, but that will take some work.  And that's still
> different from a simpler doc-string thing.

Posted on the users mailing list.