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.
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.
This package allows using an alternative syntax for machine-readable comments. Essentially, most comments of the form:
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.