#lang scribble/doc @(require "common.ss" (for-label "comics.ss")) @title[#:tag "defproc"]{API Specification} @declare-exporting["comics.ss"] Targets for code hyperlinks are defined by @scheme[defproc] (for functions), @scheme[defform] (for syntactic forms), @scheme[defstruct] (for structure types), @scheme[defclass] (for classes in the object system), and other such forms---one for each form of binding. When a library defines a new form of binding, an associated documentation library can define a new form for documenting the bindings. As we demonstrated in @Secref["code"], the @scheme[defproc] form documents a function given its name, information about its arguments, and a contract expression for its result. Information for each argument includes a contract expression, the keyword (if any) for the argument, and the default value (if any). For example, a @scheme[louder] function that consumes and produces a string might be documented as follows: @; @scr:code-block|{ @defproc[(louder [str string?]) string?]{ Adds ``!'' to the end of @scheme[str]. } }| @; The description of the function refers back to the formal argument @schemeidfont{str} using @scheme[scheme]. In the typeset result, the reference to @schemeidfont{str} is typeset in a slanted font both in the function prototype and description. @; @snested{ @defproc[(louder [str string?]) string?]{ Adds ``!'' to the end of @scheme[str]. } } @; As usual, lexical scope provides the connection between the formal-argument @schemeidfont{str} and the reference. The @scheme[defproc] form expands to a combination of Scribble functions to construct a table representing the documentation and Scheme local-macro bindings to control the expansion and typesetting of the procedure description. For the above @scheme[defproc], the @scheme[for-label] binding of @scheme[louder] partly determines the library binding that is documented by this @scheme[defproc] form. A single binding, however, can be re-exported by many modules. On the reference side, the @scheme[scheme] and @scheme[schemeblock] forms follow re-export chains to discover the first exporting module for which a binding is documented; on the definition side, @scheme[defproc] needs a declaration of the module that is being documented. The module declaration is no extra burden on the document author, because the reader of the document needs some indication of which module is being documented. The @scheme[defmodule] form both generates the user-readable explanation of the module being documented and declares that all definitions within the enclosing section (and sub-sections, unless overridden) correspond to exports from the declared module. Thus, if @scheme[louder] is exported by the @schemeidfont{comics/string} library, it is documented as follows: @; @code-block|{ #lang scribble/doc @(require scribble/manual (for-label scheme/base comics/string)) @title{String Manipulations} @defmodule[comics/string] @defproc[(louder [str string?]) string?]{ Adds ``!'' to the end of @scheme[str]. } }| The @scheme[defproc] form is implemented by a @schememodname[scribble/manual] layer of Scribble, which provides many functions and forms for typesetting PLT Scheme documentation. The @scheme[scribble/manual] layer is separate from the core Scribble engine, however, and other libraries can build up @scheme[defproc]-like abstractions on top of the core typesetting and cross-referencing capabilities described in @Secref["struct"].