Go to the first, previous, next, last section, table of contents.


Enhancing Documentation with Machine-Readable Comments

Author(s): Manuel Hermenegildo.

Version: 1.9#58 (2002/4/19, 20:59:33 CEST)

This defines the admissible uses of the comment/2 declaration (which is used mainly for adding machine readable comments to programs), the formatting commands which can be used in the text strings inside these comments, and some related properties and data types. These declarations are ignored by the compiler in the same way as classical comments. Thus, they can be used to document the program source in place of (or in combination with) the normal comments typically inserted in the code by programmers. However, because they are more structured and they are machine-readable, they can also be used to generate printed or on-line documentation automatically, using the lpdoc automatic documentation generator. These textual comments are meant to be complementary to the formal statements present in assertions (see the assertions library).

Usage and interface (comments)

Documentation on exports (comments)

PROPERTY: docstring/1:

Defines the format of the character strings which can be used in machine readable comments ( comment/2 declarations) and assertions. These character strings can include certain formatting commands.

Usage: docstring(Text)

PROPERTY: stringcommand/1:

Defines the set of structures which can result from parsing a formatting command admissible in comment strings inside assertions.

In order to make it possible to produce documentation in a wide variety of formats, the command set is kept small. The names of the commands are intended to be reminiscent of the commands used in the LaTeX text formatting system, except that "@" is used instead of "\." Note that \ would need to be escaped in ISO-Prolog strings, which would make the source less readable (and, in any case, many ideas in LaTeX were taken from scribe, where the escape character was indeed @!).

The following are the currently admissible commands.

Usage: stringcommand(CO)

REGTYPE: version_descriptor/1:

A structure denoting a complete version description:

version_descriptor(version(Version,Date)) :-
        version_number(Version),
        ymd_date(Date).
version_descriptor(version(Version,Date,Time)) :-
        version_number(Version),
        ymd_date(Date),
        time_struct(Time).

Usage: version_descriptor(Descriptor)

REGTYPE: filetype/1:

Intended uses of a file:

filetype(module).
filetype(user).
filetype(include).
filetype(package).
filetype(part).

Usage: filetype(Type)

Documentation on internals (comments)

DECLARATION: comment/2:

This declaration provides one of the main means for adding machine readable comments to programs (the other one is adding documentation strings to assertions).

Usage 1: :- comment(CommentType,TitleText).

Usage 2: :- comment(CommentType,SubTitleText).

Usage 3: :- comment(CommentType,AuthorText).

Usage 4: :- comment(CommentType,AckText).

Usage 5: :- comment(CommentType,CopyrightText).

Usage 6: :- comment(CommentType,SummaryText).

Usage 7: :- comment(CommentType,CommentText).

Usage 8: :- comment(CommentType,CommentText).

Usage 9: :- comment(CommentType,CommentText).

Usage 10: :- comment(PredName,CommentText).

Usage 11: :- comment(CommentType,CommentText).

Usage 12: :- comment(Version,CommentText).

Usage 13: :- comment(CommentType,VersionMaintenanceType).

Usage 14: :- comment(CommentType,PredName).

Usage 15: :- comment(CommentType,PredName).

Usage 16: :- comment(CommentType,PredName).

Usage 17: :- comment(CommentType,PredName).

Usage 18: :- comment(CommentType,FileType).

Usage 19: :- comment(CommentType,FileName).

REGTYPE: version_number/1:

Version is a structure denoting a complete version number (major version, minor version, and patch number):

version_number(Major*Minor+Patch) :-
        int(Major),
        int(Minor),
        int(Patch).

Usage: version_number(Version)

REGTYPE: ymd_date/1:

A Year/Month/Day structure denoting a date:

ymd_date(Y/M/D) :-
        int(Y),
        int(M),
        int(D).

.

Usage: ymd_date(Date)

REGTYPE: time_struct/1:

A struture containing time information:

time_struct(Hours:Minutes*Seconds+TimeZone) :-
        int(Hours),
        int(Minutes),
        int(Seconds),
        atm(TimeZone).

Usage: time_struct(Time)

REGTYPE: version_maintenance_type/1:

Possible kinds of version maintenance for a file:

version_maintenance_type(on).
version_maintenance_type(off).
version_maintenance_type(dir(Path)) :-
        atm(Path).

The automatic maintenance of version numbers is typically done by the Ciao emacs mode.

Usage: version_maintenance_type(Type)


Go to the first, previous, next, last section, table of contents.