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

On Fri, Jun 24, 2011 at 9:27 AM, Sam Tobin-Hochstadt <samth at ccs.neu.edu> wrote:
> 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

Ah, right. Sorry.

I think the problem is that with-handlers is actually called
with-handlers: in the place where it exported (as far as the
declare-exporting is concerned) so it is not getting connected with
the identifier named with-handlers after the renaming happens.

That is, way to interpret the argument to #:with-sources is "I am
documented exports from this module" and the earlier arguments to
declare-exporting (typed/scheme/base typed/scheme typed-scheme in this
case) are just used in the documentation to print out what the exports
are; they aren't actually used in a meaningful way internally in
scribble to connect anything to anything else.

So I think the fix is to do the renaming for with-handlers before it
gets exported from typed-scheme/base-env/prims (or introduce another
module and put that one in the #:use-sources and use it as the one
where the re-providing is happening).

I didn't actually try this out (I made a quick attempt, but there are
several changes required to just move the renaming into prims.rkt),
tho, so I may be getting this wrong....

Robby