[racket-dev] OK, how do I fix this DrDr complaint?

At Tue, 5 Jul 2011 09:23:38 +0800, Robby Findler wrote:
> On Tue, Jul 5, 2011 at 8:52 AM, Sam Tobin-Hochstadt <samth at ccs.neu.edu> wrote:
> > On Mon, Jul 4, 2011 at 8:36 PM, Stephen Bloch <sbloch at adelphi.edu> wrote:
> >> As of this evening's DrDr build, test-docs-complete is complaining of a
> >> gazillion "undocumented exports" from picturing-programs.  In fact, these
> >> identifiers are all required from 2htdp/image and re-exported from
> >> picturing-programs, so I didn't bother re-documenting them.  How do I tell
> >> test-docs-complete where they're documented?
> >
> > The answer is to use `declare-exporting'.  You'd write something like
> > this in the documentation for `picturing-programs':
> >
> > (declare-exporting picturing-programs #:use-sources (2htdp/image))
> >
> > Unfortunately, because of the way `declare-exporting' works, this
> > might not be entirely correct.  You need to name the file that the
> > various exports of `2htdp/image' are *defined* in, not just where
> > they're exported.  But the line above is the general direction you
> > want to go in.
> 
> I think that in this case Stephen should be fine as long as he is
> re-exporting 2htdp/image, without needing any other declarations.
> 
> Your typed/racket docs were more complex as you were re-exporting
> names from internal modules, not the modules where the names were
> documented as coming from.

I've expanded the docs in an attempt to clarify:

 Use `#:use-sources' sparingly, but it is needed when

   * bindings are documented as originating from a module M, but the
     bindings are actually re-exported from some module P; and

   * other documented modules also re-export the bindings from P, but
     they are documented as re-exporting from M.

 For example, the `parameterize' binding of `mzscheme' is documented as
 re-exported from `racket/base', but `parameterize' happens to be
 implemented in a private module and re-exported by both `racket/base'
 and `mzscheme'. Importing parameterize from `mzscheme' does not go
 through `racket/base', so a search for documentation on `parameterize'
 in `mzscheme' would not automatically connect to the documentation of
 `racket/base'. To make the connection, the documentation of
 `racket/base' declares the private module to be a source through
 `#:use-sources', so that any re-export of `parameterize' from the
 private module connects to the documentation for `racket/base' (unless
 a re-export has its own documentation, which would override the
 automatic connection when searching for documentation).

No `#:use-sources' declaration is needed in `picturing-programs' for
two reasons: 

 * `picturing-programs' re-exports from the documented module
   `2htdp/image'; and

 * `picturing-programs' is the re-exporter, so if any `#:use-sources'
   declaration was needed, it would need to be in the documentation for
   `2htdp/image' (on the understanding of the `2htdp/image' implementor
   that other modules should be allowed to reference some internal
   module).