Next: Cross Referencing Tool
Up: Development Support Tools
Previous: Heuristic Program Checker
  Index
The document generation tools library provides a set of predicates for
the generation of documentation from ECLiPSe program sources. The
tools generate documentation by processing the
comment/2
directives in each source file. The following is an example comment for
the n-queens example:
% comment for queen/2
:- comment(queen/2, [
summary: "Program that solves the attacking Queens problem for
an arbitrary number of queens.",
index: ["NQueens Problem"],
args: ["Data": "List modelling initial state of queens on board.",
"Args": "Solution list of Y-coordinate of each queen on the
board."],
amode: queen(+,-),
amode: queen(-,+),
amode: queen(+,+),
resat: yes,
fail_if: "A solution cannot be found where all queens are safe
from attack by every other.",
see_also:
[queens8/1, queensN/1],
desc: html("The problem is to arrange a specified number of queens
on a chessboard such that no queen attacks any other queen
The predicate takes a list representing the initial state
of the queens on the board, with each element representing
a queen and its current Y-coordinate. If a solution is
found, a list is returned specifying the safe Y-coordinate
for each queen.")
]). % end of comment directive for queen/2
There are two pertinent predicates for document generation. The first,
icompile/2 generates an
information file (.eci) by extracting information from a source file (.ecl).
The second,
eci_to_html/3,
processes this information file to produce readable HTML and plain text files.
By default, these files are placed in a subdirectory with the
same name as the information file, but without the extension.
The generated files are index.html, containing a summary
description of the library, plus one HTML and one plain text file
for each predicate that was commented using a comment/2 directive
in the source.
The following produces the queen.eci file and a queen
directory in the current directory. Within the queen directory reside
index.html, queen-2.html and queen-2.txt:
?- lib(document).
document.ecl compiled traceable 83620 bytes in 0.04 seconds
Yes (0.04s cpu)
?- icompile(queen, ".").
queen.ecl compiled traceable 1432 bytes in 0.01 seconds
/examples/queen.eci generated in 0.00 seconds.
Yes (0.01s cpu)
?- eci_to_html(queen, ".", "").
Yes (0.00s cpu)
Warwick Harvey
2004-08-07