3 Scribble Definition Parser

(require (planet orseau/lazy-doc:1:2/defs-parser))

This module provides tools to easily write documentation for planet packages. It builds on the Simple Parser (see Simple Text Parser).

The Scribble Definition Parser reads scheme plain text files and generates a corresponding documentation. It currently lacks many features and is certainly not perfect to build fully reliable documentations, but it can be used at least as a helper to semi-automate the process.

This parser is meant to be used by either lazy people who don’t like documenting sources, or think it takes too much time, or those that want to document their sources incrementally (i.e., do some doc now, do the rest later). Consider using the built-in inline source documentation of Scribble if your are not as lazy as me.

Contracts and descriptions of functions and forms are added as comments in the (plain text) source files. Most of the job is done automatically by the parser, like writing function and form names, argument names, keywords and default values, and even some of the contracts.

It allows for incremental documenting, ranging from writing nothing to writing restrictive contracts and text. When contracts are not provided, the parser tries to use some default conventions (e.g., l is given the contract list?), and if that fails too, then the most general ones are used.

It is always possible to fall-back to the default Scribble documentation by using ;[:skip] before a given definition and then documenting it as Scribble code inside ;:  comments.

This parser does not yet use the real contracts used in Scheme sources and the one used are written inside comments and are for documentation purposes only (i.e., they are not added to Scheme code).

3.1 In-Source Documenting

The parser provides some comment-commands to document source code inside the source-code.

3.1.1 Documenting Modules

To write a line of text that will be added to the ".scrbl" file, just write a comment starting with ;:  followed by the text, which can of course contain scribble commands that will be interpreted and PLaneT will compile the ".scrbl" files.

To add a title to the module, just use the command ;[:title My Title].

To add a section, use ;[:section My Section]. Same for subsection. If you want to use ; my text instead of ;: my text for several lines, surround the paragraph with the lines ;[:text] and ;[:end-text].

3.1.2 Documenting Definitions

An important part of documenting is to describe definitions (of functions, forms, etc.) and to give contracts to the arguments. This parser provides tool to make it simpler in many cases. It automatically recognizes functions with keywords and default arguments, some forms (when the head of the form provides information on how it works), and parameters. Furthermore, it only parses definitions that the module provides. It also parses require to correctly output relative paths in the ".scrbl" file.

See Package Utilities for functions that augment the ".scrbl" file with useful information.

If the parser does not (yet) recognize a definition, you can still document it with scribble functions, preceded by ;: . If the parser fails to properly recognize a definition, you can precede it with the ;[:skip] command, and then document it like if the definition is not recognized.

To document a given function, text must be added after the head of the function and before its body, and must be preceded by ;: . In such text, if the parser reads a $ followed by a scheme identifier (but with no dot in it), say $foo, it is translated into @scheme[foo]. More complex expressions can of course use directly @scheme[].

Here is an example on how to write the description text of a function:

(define (foo x [name 'me])

;: Returns the string "foo" followed by $x

;: and the $name.

( .... ))

3.1.3 Contracts

It is possible to write contracts for the function arguments and for the return value:

The parser creates only documentation contracts, which do not interfere with actual contracts defined in Scheme for the module.

A more concise contract definition can be used, without repeating the argument ids:

If a contract is not given, it defaults to any or any/c, except when a convention can be used.

3.1.4 Conventions

Sometimes the programmer uses untold conventions for function argument ids, like lst for a list, str for a string, etc. The parser can take advantage of such conventions to avoid writing such obvious contracts. For example:

There also exists the ;[:remove-convention x] to remove a convention that was previously bound to x, and also ;[:remove-all-conventions].

Some default conventions are already defined:

Others may be added in future versions or upon request.

Conventions can also be managed programmatically using add-convention, remove-convention, remove-all-conventions, and the conventions parameter.

3.1.5 Writing Examples

To insert examples of interactions, surround your examples with ;[:examples] and ;[:end-examples]. It uses the examples scribble function, but automatically creates an evaluator that requires the current module. Examples must be preceded by ; and not ;: . For example:

3.2 Definitions

The following definitions are provided to allow for possible extensions or modifications of the parser’s default behavior but are not necessary to generate scribble documentation. To generate ".scrbl" files with this parser, see the Package Utilities module.