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