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

On Jun 23, 2011 6:17 PM, "Robby Findler" <robby at eecs.northwestern.edu>
wrote:
>
> Is the with-handlers that typed/racket exports the same identifier as
> the one exported by racket, or is it a different binding?

'with-handlers' in 'typed/racket' is a different binding.  Basically, it
just adds some annotations to help the type checker.

>
> Robby
>
> On Fri, Jun 24, 2011 at 2:46 AM, Sam Tobin-Hochstadt <samth at ccs.neu.edu>
wrote:
> > On Wed, Jun 22, 2011 at 6:53 PM, Robby Findler
> > <robby at eecs.northwestern.edu> wrote:
> >> To really know what is going on, one has to trace thru the re-provides
> >> for each of these identifiers and match them up to the
> >> declare-exporting declarations.
> >>
> >> In the declaration below, you're essentially saying "any identifiers
> >> documented in this module should appear to come from the
> >> typed/scheme/base, typed/scheme, and typed-scheme modules, but they
> >> are really actually exported from one of the modules listed in the
> >> #:use-sources keyword" which means, to the documentation system that
> >> any module that re-exports an identifier from, say,
> >> typed-scheme/base-env/base-types-extra, will have its documentation
> >> attached to the docs in the file with the declare-exporting below and
> >> the docs system will then point userse to typed/scheme/base.
> >>
> >> I don't think that this is what you want, since you probably want to
> >> to point people to typed/racket.
> >
> > That's not what's going on here, although you couldn't tell that from
> > my email.  That `declare-exporting' is in a subsection which only
> > documents `typed/scheme' etc, and not any of the actual forms in Typed
> > Racket.
> >
> >> To know what the right answer is for the declare-exporting below, I'd
> >> have to know how typed/racket fits into the picture. In particular, is
> >> it re-exporting things from typed/scheme? Or from those helper modules
> >> you have listed? Or from some other place?
> >
> > It's probably easier to just consider `typed/racket/base' and
> > `typed/scheme/base' here.  Both of them export identifiers from the
> > modules listed in the `declare-exporting' declaration. For example,
> > `with-handlers' is defined in `typed-scheme/base-env/prims'.
> >
> > Here's what the documentation for `typed/racket/base' looks like:
> >
> > @(defmodulelang* (typed/racket/base typed/racket)
> >                 #:use-sources
> >                    (typed-scheme/typed-scheme
> >                     typed-scheme/base-env/prims
> >                     typed-scheme/base-env/extra-procs
> >                     typed-scheme/base-env/base-types
> >                     typed-scheme/base-env/base-types-extra))
> >
> > Also, I don't think this is a problem with the general setup of
> > documentation for Typed Racket.  In particular, the identifier
> > `define-type' is defined in the same module as `with-handlers', and it
> > gets handled properly by Scribble, by DrRacket, and by `check-docs'.
> > You can see this by searching for `define-type' in the documentation,
> > or for `U', which is defined in the same module as `->'.
> >
> > Instead, I think the problem is that `with-handlers' and `->' are both
> > identifiers exported from `racket', and this is causing some sort of
> > confusion in the Scribble doc system, but I don't know exactly what,
> > and I'm therefore confused about how to try to fix it.  Of course, it
> > might be something totally different, also -- the vagaries of Scribble
> > linking are still opaque to me.
> >
> >
> >>
> >> Robby
> >>
> >> On Thu, Jun 23, 2011 at 3:16 AM, Sam Tobin-Hochstadt <samth at ccs.neu.edu>
wrote:
> >>> Currently, the documentation completeness checker (a wonderful tool;
> >>> thanks, Robby!) for Typed Racket complains that `->' and
> >>> `with-handlers' are not documented when provided from `typed/scheme',
> >>> `typed/scheme/base', and `typed-scheme'.  However, these identifiers
> >>> are fine when provided from `typed/racket', and are both defined in
> >>> modules where `check-docs' finds the documentation for other things
> >>> just fine, such as `define:' and `All'.  The documentation looks like
> >>> this:
> >>>
> >>> (declare-exporting typed/scheme/base typed/scheme typed-scheme
> >>>                    #:use-sources
> >>>                    (typed-scheme/typed-scheme
> >>>                     typed-scheme/base-env/prims
> >>>                     typed-scheme/base-env/extra-procs
> >>>                     typed-scheme/base-env/base-types
> >>>                     typed-scheme/base-env/base-types-extra))
> >>>
> >>> where `->' is defined in `typed-scheme/base-env/base-types-extra' and
> >>> `with-handlers' is defined in `typed-scheme/base-env/prims'.
> >>>
> >>> Is there something else I should be doing here?  Is there a bug in
> >>> `check-docs'?
> >>> --
> >>> sam th
> >>> samth at ccs.neu.edu
> >>> _________________________________________________
> >>>  For list-related administrative tasks:
> >>>  http://lists.racket-lang.org/listinfo/dev
> >>>
> >>
> >
> >
> >
> > --
> > sam th
> > samth at ccs.neu.edu
> >
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/dev/archive/attachments/20110623/d88d1c6d/attachment.html>