On 04/13/2012 10:55 AM, Jay McCarthy wrote:
On Fri, Apr 13, 2012 at 10:28 AM, Ryan Culpepper<r...@cs.utah.edu> wrote:
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.
This compile-time table strategy wouldn't work if they were in
different Scribble files though, right?
The declaration forms would have to be in a module required by all
Scribble files that depended on the relationships that they declared.
Actually, it looks like 'declare-exporting' doesn't have any important
compile-time behavior, so if you're willing to poke around in the
Scribble internals (ie, use '*declare-exporting' directly) you could use
a run-time table instead. (See scribble/private/manual-mod.)
Ryan
_________________________
Racket Developers list:
http://lists.racket-lang.org/dev
