Literate programming is an established field. The TeX source is one
of the first and best known examples of this approach, where input files
are a mixture of TeX and Pascal source. External tools are used to
untangle the common source and process one branch to produce the
documentation, while the other is compiled to produce the program.
A program and its documentation consists of various different parts:
- The program text itself. This is the minimum that must be handed to
the compiler to create an executable (module).
- Meta information about the program: author, modifications, license,
etc.
- Documentation about the overall structure and purpose of the source.
- Description of the interface: public predicates, their types, modes
and whether or not they are deterministic as wel as an informative text
on each public predicate.
- Description of key private predicates necessary to understand how
the public interface is realised.
Structured comments or directives
Comments can be added through Prolog directives, a route taken by
Ciao Prolog with lpdoc Hermenegildo,
2000 and Logtalk
Moura, 2003. We feel
structured comments are a better alternative for the following reasons:
- Prolog programmers are used to writing comments as Prolog comments.
- Using Prolog strings requires unnatural escape sequences for string
quotes and long literal values tend to result in hard to find
quote-mismatches. Python uses comments in long strings, solving this
problem by using three double quotes to open and close long comments.
- Comments should not look like code, as that makes it more difficult
to find the actual code.
We are aware that the above problems can be dealt with using
syntax-aware editors. Only a few editors are sufficiently powerful to
support this correctly, though, and we do not expect the required
advanced modes to be widely available. If comments are used, we do not
need to force users into using a particular editor.
Wiki or HTML
JavaDoc uses HTML as markup inside the structured comments. Although
HTML is more widely known than ---for example--- LaTeX or TeXinfo, we
think the Wiki approach is sufficiently widely known today. Using text
with minimal layout conventions taken largely from plaintext newsnet and
E-mail, Wiki input is much easier to read in the source-file than HTML
without syntax support from an editor.
Types and modes
Types and modes are not a formal part of the Prolog language.
Nevertheless, their role goes beyond pure documentation. The test-system
can use information about non-determinism to validate that deterministic
calls are indeed deterministic. Type information can be used to analyse
coverage from the test-suite, to generate runtime type verification or
to perform static type-analysis. We have chosen to use a structured
comment with formal syntax for the following reasons:
- As comments, they stay together with the comment block of a
predicate. We feel it is best to keep documentation as close as possible
to the source.
- As we parse them separately, we can pick up argument names and
create a readable syntax without introducing possibly conflicting
operators.
- As comments, they do not introduce incompatibilities with other
Prolog systems.
Few requirements
SWI-Prolog aims at platform independence. We want tools to rely as
much as possible on Prolog itself. Therefore, the entire infrastructure
is written in Prolog. Output as HTML is suitable for browsing and not
very high quality printing on virtually all platforms. Output to LaTeX
requires more infrastructure for processing and allows for producing
high-quality PDF documents.
