[racket-dev] Strange problem with `check-docs' and `#:use-sources'

On Thu, Jun 23, 2011 at 9:19 PM, Robby Findler
<robby at eecs.northwestern.edu> wrote:
> On Fri, Jun 24, 2011 at 8:58 AM, Sam Tobin-Hochstadt <samth at ccs.neu.edu> wrote:
>>
>> On Jun 23, 2011 6:39 PM, "Robby Findler" <robby at eecs.northwestern.edu>
>> wrote:
>>>
>>> I think I'd need to actually look at the code next. I didn't seem to
>>> find it, tho; can you give me a pointer?
>>
>> It should be in 'collects/typed-scheme/scribblings/ts-reference.scrbl' for
>> typed/racket and
>> 'collects/typed-scheme/scribblings/reference/compatibility.scrbl' for
>> typed/scheme.
>
> I don't see any docs for with-handlers in there:
>
> [robby at gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$ find
> . -name \*scrbl -exec grep -H with-handlers {} \;
> [robby at gaoping] ~/git/exp/plt/collects/typed-scheme/scribblings$
>
> Perhaps the confusion is this?: scribble only associates documentation
> with actual bindings (well, when you have re-exporting and use
> #:with-sources the situation is more complex, but what I'm writing in
> this sentence is the right way to think of it as a baseline and then
> other things are exceptions) so because the typed/racket with-handlers
> binding is a different binding, it needs different @def<whatever>.
>
> And, as further rationale for that (something that has been said
> before, but I forget if it was said here or not), macros can tell the
> difference so documenting the bindings separately, even if all the
> docs say is "behaves like X [with link]", is the right thing.
>
> Or are there actually docs that I still just didn't find?

I think your copy of the tree must be out of date; you can see the
docs for `with-handlers' in git head here:
https://github.com/plt/racket/blob/master/collects/typed-scheme/scribblings/reference/special-forms.scrbl#L387

-- 
sam th
samth at ccs.neu.edu