Documenting with PrologDoc

We consider some concrete examples of using PrologDoc.

Consider putting in a file the following predicate definition that sorts a list:

:-use_module(library(lists)).

% quicksort(List1,List2)
%          True if Ys is a sorted version of [X|Xs]
quicksort([X|Xs],Ys) :-
          partition(Xs,X,Littles,Bigs),
          quicksort(Littles,Ls),
          quicksort(Bigs,Bs),
          append(Ls,[X|Bs],Ys).
quicksort([],[]).

% partition(List,Pivot,Smaller,Greater)
% True if Smaller is a list of the values in List that are <= Pivot and
% Greater is a list of the values in List that are > Pivot
partition([X|Xs],Y,[X|Ls],Bs) :- X =< Y, partition(Xs,Y,Ls,Bs).
partition([X|Xs],Y,Ls,[X|Bs]) :- X > Y, partition(Xs,Y,Ls,Bs).
partition([],Y,[],[]).

Running PrologDoc on the program above will yield the following results (in an informal style): QuickSort Program Documentation

Note that without writing any PrologDoc style comments you still got:

An index of all predicates
An index of all files (only one in this case)
A web page describing the file quicksort.pl,

specifying the arity of all predicates in the file
specifying the Sicstus libraries used

Now, if you would like more exciting documentation, all you need to do is to add PrologDoc style comments. Consider changing your file to contain:

/***
@descr This file was created to be an simple example for <b> PrologDoc </b>. With this file you can sort a list.
@author John Smith
@date November 4, 1999
*/

:-use_module(library(lists)).

/**
   @form quicksort(List1,List2)
   @constraints
         @ground List1
         @unrestricted List2
    @descr True if Ys is a sorted version of [X|Xs]
*/
quicksort([X|Xs],Ys) :-
          partition(Xs,X,Littles,Bigs),
          quicksort(Littles,Ls),
          quicksort(Bigs,Bs),
          append(Ls,[X|Bs],Ys).
quicksort([],[]).

/**
    @form partition(List,Pivot,Smaller,Greater)
    @constraints
            @ground List
            @ground Pivot
            @unrestricted Smaller
            @unrestricted Greater
    @descr True if Smaller is a list of the values in List that are <= Pivot and
                 Greater is a list of the values in List that are > Pivot
*/
partition([X|Xs],Y,[X|Ls],Bs) :- X =< Y, partition(Xs,Y,Ls,Bs).
partition([X|Xs],Y,Ls,[X|Bs]) :- X > Y, partition(Xs,Y,Ls,Bs).
partition([],Y,[],[]).

Now, running prologdoc will yield the following documentation: More Exciting Quicksort Documentation
Note that you now get the following added features:

A general description of the file including:

The purpose of the file
The authors
The date of creation

A full description of each predicate including:

The general form of the predicate
The constraints on the variables in the predicate
A description of the predicate

Documentation of PrologDoc Using PrologDoc

As another example, we documented the PrologDoc program using PrologDoc style comments. We have included for your convenience the PrologDoc documentation of the PrologDoc files:

Enjoy!!