Source code documentation in Racket (Scheme)

Question

Is it possible to write documentation in source files like in Common Lisp or Go, for example, and extract it from source files? Or everybody uses Scribble to document their code?

Answer 1

The short answer is you can write in-source documentation by using scribble/srcdoc.

Unlike the other languages you mentioned, these aren't "doc strings":

• Although you can write plain text, you have full Racket at-expressions and may use scribble/manual forms and functions.

• Not only does this allow for "richer" documentation, the documentation goes into its own documentation submodule -- similar to how you can put tests into test submodules. This means the documentation or tests add no runtime overhead.

You do need one .scrbl file, in which you use scribble/extract to include the documentation submodule(s). However you probably want such a file, anyway, for non-function-specific documentation (topics such as introduction, installation, or "user's guide" prose as opposed to "reference" style documentation).

Of course you can define your own syntax to wrap scribble/srcdoc. For example, in one project I defined a little define/doc macro, which expands into proc-doc/names as well as a (module+ test ___) form. That way, doc examples can also be used as unit tests.

How Racket handles in-source documentation intersects a few interesting aspects of Racket:

• Submodules let you define things like "test-time" and "doc-time" as well as run-time.

• At-expressions are a different syntax for s-expressions, especially good when writing text.

• Scribble is an example of using a custom language -- documentation-as-a-program -- demonstrating Racket's ability to be not just a programming language, but a programming-language programming language.