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.
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/users
