[ Directives | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

comment(+Type, +Information)

Adding documentational information to ECLiPSe files.

Type: Comment type
Information: Information for Type

Description

The comment/2 predicate allows documentational information to be added to ECLiPSe modules which can then be extracted and processed automatically by using the document tools in the document library. Please note that any reference to `comment' in the rest of this description means the comment predicate, not the normal ECLiPSe comment (% and /* ... */).

Operationally, comment/2 always succeeds, so it is a no-op and is ignored by ECLiPSe when executed. In order to be processed by the document tools, it should appear as a directive in the program, i.e. as

:- comment(Type, Information).

A comment directive provides information on various aspects of the module in which the comment occurs. The Type argument specifies what the aspect is, and Information gives the information associated with that aspect. Some restrictions should be observed to the placement of comments to allow automatic processing to correctly process the comments. These are listed at the end. The documentation generation tools and the tkeclipse library browser tool make use of the comments to generate documentations for modules. They recognise several comment types as specified by the Type argument and extract the information accordingly. The comments can occur in any order inside the module, and none are compulsory; if they are missing, then the information they could have provided is simply not used in the documentation generation. Most comment type should only occur at most once per module unless marked *multiple* in the following description. In the case of *multiple*, all occurrence of the comments of the type are processed by the documentation tools. Otherwise, only the first textual occurrence will be used.

The documentation tools recognise the following module-level comments:

comment(summary, String): String is a short (one line) summary of the module.
comment(desc, Description): Description is a longer Text (see below) describing the module in more detail than summary.
comment(alias, String) *once* per file: String is used to override the module name used by the document processing for the comments in the file. This allows the user to generate groupings of comments in the documentation other than the module in which the comments resides.
comment(status, String): String is a single word, describing the status of the library. Classification used in ECLiPSe: prototype, evolving, stable, phase_out, deprecated.
comment(author, String): String is the name of author(s) of the module.
comment(copyright, String): String is the copyright notice that the documentation library will generate for the documentations it produce from the comments.
comment(date, String): This is designed for version control. String is a time-stamp for the file. With CVS version control software, the string can initially be set to "$Date$", which will be expanded by CVS into the actual date each time the file is checked in.
comment(include, FileNames) *multiple*: FileNames is either one file name or a list of file names. The file name is either a string or an atom. These are names of files in which additional comments for the module are located. They are only processed by the document library tools.
comment(index, ListOfStrings): The strings are used by the documentation generation process to provide pointers in the document index to the module: each string is added to the index pointing at the module description. This is used to add extra entries in the index in addition to the ones that are automatically generated.

In addition, it is possible to comment individual predicates and structures, using comment directives of the form:

comment(Name/Arity, ListofProperties) *once* for each Name/Arity: Name and Arity are the specification for a predicate in the module and ListofProperties is a list of information for the predicate. The entries are described below.
Instead of a list of properties, the atom 'hidden' can be specified. This will prevent an undocumented, exported predicate from showing up in the generated library documentation.
comment(struct(Name), ListofProperties) *once* for each structure: Name is the name of a structure and ListofProperties is a list of information for the structure. The entries are described below (admissible properties are: summary, fields, desc, see_also, eg, index).

In these comments, the ListOfProperties is a list of properties of the form:

    PropertyName: PropertyInformation

The properties can occur in any order in the list. The following ones are recognized by the document tools:

amode: FunctorTemplate *multiple*

FunctorTemplate is a structure corresponding to the functor of the predicate with the argument filled in with the mode specifications. The valid modes are those generally recognised by ECLiPSe (+, ++, -, ?). This property can occur multiple times, each giving a different mode for the predicate. The document tools will generate the multiple modes description in the detail description of the predicate, but will combine the modes by generalising all the amodes to general the general template for the predicate in any summary description of the predicate.

args: ListofArgs

ListofArgs is a list of the argument descriptions describing the argument. The length of the list should correspond to the arity of the predicate. The argument description is of the form:

      ArgName: Description

where both ArgName and Description are strings. If present, ArgName will be used in the mode template.

desc: Description

Description is a Text (see below) giving a long description of the predicate.

eg: Description

Description is a Text (see below) for examples of using the predicate. This is used to generate the Examples section of the predicate description.

exceptions: ListofErrors

ListofErrors is a list of error description of the form:

      Int: Text

where Int is a error code for an error that can occur with the predicate and Text describes the error. This is used to generate the `Exceptions' section of the predicate description.

fail_if: Text

Text is a string describing the fail conditions for the predicate. It is used to generate the `Fail Conditions' section of the predicate description.

fields: ListofFields *structures only*

ListofFields is a list of the field descriptions describing the structure fields. A field description is of the form:

      FieldName: Description

where FieldName is an atom or string and Description is a Text.

index: ListofStrings

Each string in ListofString will be added to the index generated by the document tools, pointing at the predicate. This is used to add additional index entries for the predicate in addition to the predicate names that is generated automatically.

resat: Resatisfiable

Resatisfiable is either yes or no, specifying if the predicate is resatisfiable. This is used to generate the `Resatisfiable' section of the predicate description.

see_also: ListofSpecs

ListofSpecs is a list of items, referring to other predicates and libraries which are related to the commented predicate. The specs can be of the form Name/Arity, LibName:Name/Arity, or library(LibName). This is used to generate the `See Also' section of the predicate description.

summary: String *compulsory*

String is a short (one line) summary of the predicate.

template: String

This is normally not needed. It is only useful to override the most general default template that will otherwise be automatically generated from the predicate name, the arguments and and the amode information.

Note that only the 'summary' property is compulsory, and apart from 'amode', each property should occur at most once.

For the longer descriptions in the comments, a `Text' is allowed. This is either a normal ascii string or a string in a document markup language. In the latter case, the string must be enclosed in a wrapper. Currently the following are supported:

html(String): String is in HTML format and can contain HTML tags. Special characters must be written using HTML notation. The string must be embeddable into an HTML document, i.e. there should be no <html> .. </html> and no headings.
ascii_fmt(String): String is in ascii format. It will be rendered using a proportional font and spacing and line breaks will be lost.
ascii(String): String is in ascii format. It can consist of multiple lines and will be rendered using a fixed width font with all spacing and line breaks being preserved. (To break lines without inserting a significant line break, precede the line break with a '\').
String: The same as ascii_fmt(String), except in the 'eg' field where it is interpreted as ascii(String).

In order to allow automatic processing, the following should be observed with the placement of comments:

A comment should occur in a file.
A comment must occur as a directive.
A comment applies to a module, so it should occur textually inside a module, i.e. after any module declarations. If the program does not contain any module declarations, the file name (without suffix) is assumed to be the module.
The file containing comments should only have a single module defined.

Note that in addition to allowing automatic documentation generation, the comment predicates can also be used to provide information on the module itself when the user reads the program. Thus it can also act as comments in the same way as the traditional comments, but in a more structured way.

Fail Conditions

None. Always succeed.

Resatisfiable

Examples

% comments for the document library
:- comment(summary, "Automatic document generation library").

:- comment(index, ["Literate programming",
                   "automatic documentation generation"]).

% comment for comment/2
:- comment(comment/2, [

    summary: "Adding documentational information to ECLiPSe files.",

    index: ["Literate programming"],

    args: ["Type": "Comment type",
       "Information": "Information for Type"],

    amode: comment(+,+),

    resat: no,

    fail_if: "None. Always succeed.",

    see_also:
	[icompile/1,icompile/2,eci_to_html/3,ecis_to_htmls/0,ecis_to_htmls/3],

    desc: html("    The comment/2 predicate allows documentational information to be added to
    .....
    "),

    eg: "
    % comments for the document library
    :- comment(summary, \"Automatic document generation library\").

    ....the other examples you are seeing now
    "

    ]).  % end of comment directive for comment/2


% other examples
:- comment(fcompile/2, [
    summary: "Generates an object file from the ECLiPSe source File in module Module.",
    args: ["File":"Name of source file (Atom or string)",
              "Module":"Name of module (Atom)"],
   amode: fcompile(+,+)
    ]).


:- comment(atom_string/2, [
    summary: "Conversion between an atom and a string.",
    args: ["Atom": "Atom or variable",
       "String": "String or variable"],
    amode: atom_string(+,?), amode: atom_string(?,+),
    desc: "\
    If Atom is instantiated, converts it to a string String.
    If String is instantiated, converts it to an atom Atom.",

    resat: no,

    fail_if: "\
    Fails if the string String does not unify with the string version of the
    atom Atom.",

    exceptions: [5: "Atom is instantiated, but not to an atom.",
	5: "String is instantiated, but not to a string.",
	4: "Neither Atom nor String are instantiated."]
    ]).