#lang scribble/doc
@(require "common.ss")
@title[#:tag "srcdoc"]{In-Code Documentation}
For some libraries, the programmer may want to write documentation
with the source instead of in a separate document. To support such
documentation, we have created a Scheme/Scribble extension that is
used to document some libraries in the PLT Scheme distribution.
Using this extension, the @schemeidfont{comics/string} module could be
implemented as follows:
@;
@code-block|{
#lang at-exp scheme/base
(require scheme/contract
scribble/srcdoc)
(require/doc scheme/base
scribble/manual)
(define (louder s)
(string-append s "!"))
(provide/doc
[louder
([str string?] . -> . string?)
@{Adds ``!'' to the end of @scheme[str].}])
}|
The @code-elem{#lang at-exp scheme/base} line declares that the module uses
@schememodname[scheme/base] language extended with @lit["@"]-notation.
The imported
@schememodname[scribble/srcdoc] library binds @scheme[require/doc] and
@scheme[provide/doc]. The @scheme[require/doc] form imports bindings
into a ``documentation'' phase, such as the @scheme[scheme] form that is used
in the description of @scheme[louder]. The @scheme[provide/doc] form exports
@scheme[louder], annotates it with a contract for run-time checking,
and records the contract and description for inclusion in
documentation. The description is an expression in the documentation
phase; it is dropped by normal compilation of the module, but combined
with the @scheme[require/doc] imports and inferred @scheme[(require
(for-label ...))] imports to generate the module's documentation.
The documentation part of this module is extracted using
@scheme[include-extracted], which is provided by the
@scheme[scribble/extract] module in cooperation with
@scheme[scribble/srcdoc]. The extracted documentation might provide
the entire text of the document directly, or it might be incorporated
into a larger document:
@;
@code-block|{
#lang scribble/doc
@(require scribble/manual
scribble/extract
(for-label comics/string))
@title{Strings}
@defmodule[comics/string]
The @schememodname[comics/string] library
provides functions for creating punchlines.
@include-extracted[comics/string]
}|
An advantage of using @scheme[scribble/srcdoc] and
@scheme[scribble/extract] is that the description of the function is
with the implementation, and the function contract need not be
duplicated in the source and documentation. Similarly, the fact that
@scheme[string?] in the contract gets its binding from
@scheme[scheme/base] is specified once in the code and inferred for
the documentation. At the same time, a phase separation prevents
document-generating expressions from polluting the library's run-time
execution, and vice versa.