3 Structured comments
Structured comments come in two flavours, the line-comment (%) based
one, seen mostly in the Prolog community and the block-comment (/*...*/)
based one, commonly seen in the Java and C domains. As we cannot
determine the argument names, type and modes from following (predicate)
source itself, we must supply this in the comment.1See section
11. The overall structure of the comment therefore is:
- Semi-formal type- and mode-description, see section 5
- Wiki-style documentation body, see section 7
- JavaDoc style tags (
@keyword value, see section 6)
The /*...*/ style comment starts with
/**<white>. The type and mode declarations
start at the first non-blank line and are ended by a blank line.
The %-style line comments start with %!<white>
or, for compatibility reasons, with %%<white>.2The %%
leader was considered to give too many false positives on arbitrary
source code. It is still accepted, but invalid comments are silently
ignored, while invalid comments that start with %! result
in a warning. The type and mode declaration is ended by the
first line that starts with a single %. E.g., the following two
fragments are identical wrt. PlDoc. Skipping blank-lines in /**
comments allows to start the comment on the second line.
%! predicate(-Arg:type) is nondet % Predicate ...
/** * predicate(-Arg:type) is nondet * * Predicate ... */
The JavaDoc style keyword list starts at the first line starting with @<word>.