#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 kind of binding. When a library defines a new kind of binding, an associated document library can define a new form for documenting bindings. 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, the @scheme[louder] function defined above consumes a string and produces a string, and it might be documented as follows: @scr:code-block|{ @defproc[(louder [str string?]) string?]{ Adds ``!'' to the end of @scheme[str]. } }| which produces the following output: @nested{ @defproc[(louder [str string?]) string?]{ Adds ``!'' to the end of @scheme[str]. } } 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 an indication of which module is being documented, anyway. 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 the @scheme[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"].