[racket] Exploratory programming?

From: Eli Barzilay (eli at barzilay.org)
Date: Wed Dec 1 21:38:17 EST 2010

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

> 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.

          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!

Posted on the users mailing list.