PrologDoc Language

Table of Contents

  What is PrologDoc?

  Automatically Generated Information

  Predicate Specific Comments

  General File Comments

  Running PrologDoc in SICSTUS Mode

  Related Sites

What is PrologDoc?

PrologDoc is a system that automatically generates HTML documention from Prolog programs.

HTML documentation can be automatically created from any Prolog program. In addition, by documenting your program according to the PrologDoc syntax, you can enable the PrologDoc documentation to be even more useful for you.

PrologDoc can be run on a list of files to generate not only documentation about each file, but also an index file specifying all the files documented.

Back to Table of Contents

Automatically Generated Information

When documenting a Prolog program <filename>, the following information is automatically inserted in PrologDoc documentation, without user intervention:

Files that <filename> consults.

Example: If <filename> contains
:- [file1,file2].
Then file1 and file2 will be included in this list
SICSTUS libraries that <filename> uses.
Example: If <filename> contains
:- use_module(library(system)).
Then system will be included in this list
Side-effects encountered when loading <filename>.
Example: If <filename> contains
:- write('hello world').
Then this predicate will be included in this list
Predicates defined in <filename>.
Note: This list will include only exported predicates if <filename> is defined as a module.
Module name, if <filename> is defined as a module.

Back to Table of Contents

Predicate Specific Comments

Using the PrologDoc syntax enables you to extensively document predicates that you define. A PrologDoc predicate comment is defined within /** ? */. It should be placed immediately before the predicate it is documenting. The PrologDoc syntax is similar to JavaDoc. The following tags can be used within a predicate comment:

@descr - For giving a general description of the predicate

@form - Is used to define the general form of the predicate

@constraints - Used to define constraints on the parameters. After a @contraints tag there can be a series of :

@ground - to define a parameter that must be ground

@unground - to define a parameter that can not be ground

@unrestricted - to define a parameter that is not restricted
There can be several @constraints tags to define different options of constraining parameters.
Example: The following could be a predicate comment for the member predicate:
/** @form member(Value,List)
@constraints @ground Value
@unrestricted List
@constraints @unrestricted Value
@ground List
@descr True if Value is a member of List */
Back to Table of Contents

General File Comments

Using PrologDoc you can give a general description to the file. This enables you to globally document the purpose of the prolog program defined within. A general file comment are defined within /*** ? */. It may be located anywhere in the file. The following tags can be used within a predicate comment:

@descr - For giving a general description of the file

@author - To specify the name of an author

@date - To specify the date creation of the file

Note: Since the values of the tags are copied as is into the HTML documentation, HTML tags may be used within these values.

Example:

/*** @descr This file is used for many thing. Among them are:
<ul> <li> Purpose 1 ?
<li> Purpose 2 ? </ul>
@author John Smith

@date 1/1/00 */
Back to Table of Contents

Running PrologDoc in SICSTUS Mode

PrologDoc can create two different styles of HTML documentation. The documentation can either be informal, or can imitate the style of SICSTUS documentation. When the documentation mimics SICSTUS, the main difference is in how the constraints of the variables are displayed. The constraints are shown with punctuation marks (?,+,etc) next to the variables. (In regular mode the constraints are specified explicitly.)

To imitate SICSTUS documentation, run PrologDoc with the flag -s.

Back to Table of Contents

Related Sites

SICSTUS Prolog Homepage

Logic Programming Course at Hebrew University of Jerusalem

Back to Table of Contents

Back to PrologDoc Homepage