Documentation comments

Author(s): Jose F. Morales, Manuel Hermenegildo.

Stability: [devel] This is still a beta version for experimentation. Much functionality is implemented but syntax may change in the future.

This package allows including machine-readable documentation (including assertions) inside code comments. Additionally, a simpler lightweight markup syntax is enabled for (LPdoc) documentation.

The overall objective is to allow speeding up the process of documentation for many cases that do not require the full power of the documentation system and assertion language, as well as improving the portability (as documentation comments are simply ignored when not supported by other Prolog systems).

The syntax is partially inspired in the mark up syntax for Doxygen, Coqdoc, and Haddock.

Documentation comments as terms

This package enables grammar extensions that allow some special operators, which annotate the source code with documentation, are then translated as documentation assertions.

The following pieces of text are understood as both prefix or postfix operators:

%! Comment      (or)    /*! Comment */
%  ...

which is used to write arbitrary chunks of documentation (usually referring to the code after them).

%< Comment      (or)    /*< Comment */
%  ...

which is used to write chunks of documentation (usually referring to the code before them).

Comments appear in the abstract syntax tree of the parsed programs as special terms. The doccomments package extracts them from the program to generate the documentation.

Note that reading comments symbolically requires cooperation with the internal parsing routines. For more details, see the doccomments Prolog flag and its use in the read and tokenize modules.

As # "..." comments in LPdoc, this approach continues the documentation in the AST. Other systems take a similar approach (for example, see Scribble). A simpler approach could just parse documentation in one pass and generate clean code. It is not clear which one is better in the long term.

Relation with comment assertions

This package allows using an alternative syntax for machine-readable comments. Essentially, most comments of the form:

:- doc(CommentType, Body).

can be written as:

%! @CommentType Body

Body can expand over several lines but each must have a % in the first column. For example, the following:

%! @title  A nice module
% 
%  @author Pro Grammer
% 
%  @module This is a very nice module indeed. 
%          It can be used for several purposes.
%
%  @hide   internal/3

is equivalent to:

:- doc(title, "A nice module").
:- doc(author,"Pro Grammer").
:- doc(module,"This is a very nice module indeed. 
            It can be used for several purposes.").
:- doc(hide,internal/3).

See files distributed at markdown/examples/ for more examples.

Usage and interface

Library usage:
:- use_package(doccomments). or :- module(...,...,[doccomments]).
Implicit imports:
- Internal (engine) modules:
  term_basic, arithmetic, atomic_basic, basiccontrol, exceptions, term_compare, term_typing, debugger_support, basic_props.
- Packages:
  prelude, initial, condcomp, assertions, assertions/assertions_basic.