[plt-scheme] scribble question: @defproc when it's not an existing proc?
In the handin-server, there's the ability to specify a file containing
a module that exports a single function named hook. In documenting
this, would it be appropriate to use @defproc[(hook ...)], even though
'hook' is something defined by the user and not by the library? In
fact, scribble generates a warning message (basically, "I couldn't
find a definition for 'hook'")---that suggests that defproc might not
be the right choice.
I've attached the text here, just in case there are other howling
errors that I'm making in my first use of scribble.
John Clements
@item{@indexed-scheme[hook-file] --- a path (relative to handin server
directory or
absolute) that specifies a filename that contains a `hook'
module. This is useful as a general device for customizing
the server through Scheme code. The file is expected to
contain a module that provides a @scheme[hook] function, which
should be receiving three arguments:
@comment{defproc here?}
@defproc[(hook [operation symbol?] [connection-context (or/c
number? symbol? false?)]
[relevant-info (listof (list/c symbol? any))])
void?]
@comment{void appropriate here?}
The @scheme[operation] argument indicates the operation that
is now
taking place. It can be one of the following:
@indexed-scheme['server-start], @indexed-scheme['server-
connect],
@indexed-scheme['user-create], @indexed-scheme['user-
change], @indexed-scheme['login],
@indexed-scheme['submission-received], @indexed-
scheme['submission-committed],
@indexed-scheme['submission-retrieved], @indexed-
scheme['status-login],
or @indexed-scheme['status-file-get].
The @scheme[connection-context] argument is a datum
that specifies the connection context (a number for handin
connections, a @scheme['wN] symbol for servlet connections,
and @scheme[#f] for other server operations).
The @scheme[relevant-info] contains an alist of information
relevant
to this operation. Currently, the hook is used in several
places
after an operation has completed.
For example, here is a simple hook module that sends
notification messages when users are created or their
information has
changed:
@schemeblock[
(module hook mzscheme
(provide hook)
(require (lib "sendmail.ss" "net"))
(define (hook what session alist)
(when (memq what '(user-create user-change))
(send-mail-message
"course-staff at university.edu"
(format "[server] ~a (~a)" what session)
'("course-staff at university.edu") '() '()
(map (lambda (key+val)
(apply format "~a: ~s" key+val))
alist)))))]
Changes to @filepath{config.ss} are detected, the file will be re-
read, and
options are reloaded. A few options are fixed at startup time:
port numbers, log file specs, and the @scheme[web-base-dir] are as
configured at startup. All other options will change the behavior
of the running server (but things like @scheme[username-case-
sensitive?]
it would be unwise to do so). (For safety, options are not
reloaded until the file parses correctly, but make sure that you
don't save a copy that has inconsistent options: it is best to
create a new configuration file and move it over the old one, or
use an editor that does so and not save until the new contents is
ready.) This is most useful for closing & opening submissions
directories.}}