P.S. Also struct definitions.
(define-struct s (a b c))
(provide/contract
(struct s
([a integer?] ; insightful description
[b boolean?]
[c string?])))
Could be:
(define/contract/provide-struct s
([a integer?] ; insightful description
[b boolean?]
[c string?]))
or elevate the comment to an optional description:
(define/contract/provide/doc-struct s
([a integer? "insightful description"]
[b boolean?]
[c string?]))
And some analog for function definitions/contracts/provides.
Obviously all of us can make our own macros. But that makes it harder
to share code. Plus the tie-in to a help/doc system is a motivation to
standardize this. Also, I think it would help some people coming to
Racket from some other languages (at least it would have helped me).
Off soapbox.
On Thu, Dec 2, 2010 at 12:26 PM, Greg Hendershott
<greghendersh...@gmail.com> wrote:
> Although I've grown accustomed to it, early on I disliked the
> redundancy of define/contract and (my own macro)
> define/contract/provide.
>
> (define/contract (foo x #:y y)
> (int? #:y boolean?)
> ( ... body ... ))
>
> Coming from typed languages, I really wanted to state the args and the
> "types" together as one list not two.
>
> If that were possible, it would also make possible "show me the blue box".
>
> Of course, I've also learned how expensive contracts could be. So I
> sometimes have code where the contract got, not deleted, but commented
> out with #| |# because I still wanted the documentation value. And it
> would be helpful if such functions could "get blue boxes", too.
>
> Likewise, there have been times when I've wanted contracts active for
> dev/dbg purposes, but don't want them for release/production, and
> wished there could be a build or runtime switch (as opposed to
> commenting out code).
>
> I wonder if someone smarter than me could pull this all together into
> a neat syntax and system?
> - Merge function definitions and contracts into one thing, with a new
> variation of define/contract and define/contract/provide.
> - Let contracts be made inactive for performance, but remain in the
> code. Ideally can disable per-function as well as more globally like
> per-module?
> - Allow contracts' doc value to be not simply their visibility in the
> source file, but also their visibility in a help system (which again
> can use the contracts whether live or disabled) that shows us the
> "blue boxes".
>
>
> On Wed, Dec 1, 2010 at 11:12 PM, Ryan Culpepper <ry...@ccs.neu.edu> 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
