#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.