[racket] Exploratory programming?
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.
Ryan
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.
>