2Scribble Definition 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 Sscheme sources
and the one used are written inside comments and are
for documentation purposes only (i.e., they are not added to scheme code).

2.1In-Source Documenting

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

2.1.1Documenting 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].

2.1.2Documenting 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.

The package module also provides 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 @scheme[x]

;: and the @scheme[name].

( .... ))

2.1.3Contracts

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

(define (foo x [name 'me]) ;:-> string?

;: [x number?]

;: [name symbol?]

;: Returns the string "foo" followed by @scheme[x]

;: and the @scheme[name].

( .... ))

The return value is preceded byt the special comment ;:->.

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:

(define (foo x;: number?

[name 'me] ;: symbol?

);:-> string?

;: Returns the string "foo" followed by @scheme[x]

;: and the @scheme[name].

( .... ))

This will be translated to:

@defproc[(foo [ x number?] [ name symbol? 'me]) string?]{

Returns the string "foo" followed by @scheme[x]

and the @scheme[name].

}

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

2.1.4Conventions

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:

;[:convention x number?]

;[:convention z (listof string?)]

(define (foo x) ;:-> z

;: This is @scheme[foo].

(....))

(define (bar x) ;:-> z

;: This is @scheme[bar].

(....))

will be translated to:

@defproc[(foo [ x number? ]) (listof string?)]{

This is @scheme[foo].

}

@defproc[(bar [ x number? ]) (listof string?)]{

This is @scheme[bar].

}

The convention is applied to all remaining functions (but is not applied backwards).
Conventions added when parsing the source file do not persist
for future parsing of other source files.

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:

l

:

list?

lst

:

list?

ll

:

(listof list?)

n

:

number?

num

:

number?

str

:

string?

s

:

string?

sym

:

symbol?

vec

:

vector?

proc

:

procedure?

fun

:

procedure?

file

:

path-string?

path

:

path-string?

x

:

number?

z

:

(listof string?)

They have less priority than local conventions, which have less priority than
per-definition contracts.

2.1.5Writing 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:

;[:examples]

; (+ 2 7)

; (display "plop")

;[:end-examples]

will be translated to:

@(examples #:eval (make-my-eval)

(+ 2 7)

(display "plop")

)

where (make-my-eval) is defined in the generated
.scrbl file when using functions of the module package.

2.2Definitions

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

Adds a module-wise convention.
For example, if the parser reads ";[:convention text string?]"
then all following argument named text will be given the contract string? by default.
This behavior does not have the priority on per-definition contracts.

Parses the scheme plain text source file f and returns its documentation string.
by default, all definitions are parsed, but only a subset is currently supported,
like functions, parameters, and forms of the type (id. arg).
Like for scrbl-parse-text, a list of provided definitions can be supplied.