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

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?

Robby