[racket-dev] Scribble - language/module documentation and declare-exporting

On 04/12/2012 11:27 AM, Jay McCarthy wrote:
> Based on some feedback from Robby, I'm trying to improve the way the
> Web server's binding exports are documented.
>
> I've been looking at the docs and some examples, but I can't find the
> right thing to do and if it is even possible.
>
> Here's the basic setup:
>
> web-sever/http re-exports the bindings provided by web-server/http/xexpr
> web-server/servlet re-exports the bindings provided by web-server/http
> #lang web-server/insta re-exports the bindings from web-server/servlet
> #lang web-server re-exports the bindings provided by web-server/http
> and a bunch of other things
>
> Right now what I do, is at the start of each section I say that, for
> example, web-server/http exports every module "below" and then have
> the documentation for each of the modules; and similarly in the case
> of the languages, I have a list of what modules are exported.
>
> This is fine for a prose reading, but it doesn't work very well with a
> search, because if you search for 'extract-binding' it will only say
> 'web-server/http/bindings' and not the other modules, which you may
> already be requiring.
>
> My understanding is that it is possible for me to use
>
> @defmodule*/no-declare[(web-server/http/xexpr)]{}
>
> @declare-exporting[web-server/http/xexpr web-server/http]
>
> to show that web-server/http/xexpr is re-exported by web-server/http
>
> There are two problems with this:
>
> First, it is non-modular because the *exported* module has to tie
> itself to the *exporting* module, rather than the *exporting* module
> looking like
>
> @defmodule/dream-team[web-server/http #:exports (web-server/http/xexpr)]

It seems like this could be done with a couple macros and a compile-time 
table or two. For example,

   @declare-re-exports[web-server/http (web-server/http/xexpr)]

could enter the relationship in the table(s),

   @defmodule/dream-team[web-server/http]

could discover that web-server/http includes web-server/http/xexpr, if 
you wanted to produce a paragraph that mentions every module that it 
re-exports, and

   @defmodule/dream-team[web-server/http/xexpr]

could discover that web-server/http/xexpr is re-exported by 
web-server/http and automatically produce the declare-exporting 
declarations.

(I don't know the answer to your second question, though.)

Ryan


> Second, it does not appear possible to show that a module is
> re-exported by a #lang and not a module. For example "#lang
> web-server" and the "web-server" module are totally different, so
>
> @declare-exporting[web-server/http/xexpr web-server]
>
> is incorrect and misleading.
>
> Similarly, I'd like
>
> @defmodulelang/summer-lovin[web-server #:exports (web-server/http)]
>
> --
>
> Due to these two problems, I don't think it is feasible for me to
> improve the Web server docs in this way because of the vast number of
> re-exports that are going on.
>
> Unfortunately, my understanding of how Scribble is implemented
> suggests that this can't really work, because the indexing information
> is computed during expansion from the label bindings and my dream @def
> constructs wouldn't be able to propagate their information to the
> existing index entries for the underlying modules.
>
> Is there a better way to solve this problem? How feasible is it to
> change Scribble to accommodate this if not?
>
> Jay
>