+1
On Dec 1, 2010, at 11:12 PM, Ryan Culpepper wrote:
> 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
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/users
