doc_process.pl -- Process source documentation

The pldoc module processes structured comments in Prolog source files into well formatted HTML documents.

author

- Jan Wielemaker

license

- GPL

 prolog:predicate_summary(+PI, -Summary) is semidet[multifile]

Provide predicate summaries to the XPCE class prolog_predicate, used by the IDE tools.

 prolog:doc_compile_comment(+Comment:string, +Lines, +FilePos, ?Term, +VarNames, -Compiled:list) is semidet[multifile]

Hook to compile structured comments that do not document a predicate or section, such as the members of an xpce class. The hook is tried before the default processing. Lines are the indented lines of Comment and Term is the term that follows the comment. Term is unbound if Comment is not the last comment before the term. VarNames is a list Name=Var for the variables of Term. If the hook succeeds, Compiled is a list of terms as described with parse_comment/3, normally holding object(Object, Summary, Comment) and optionally signature(Object, Signature).

 is_structured_comment(+Comment:string, -Prefixes:list(codes)) is semidet

True if Comment is a structured comment that should use Prefixes to extract the plain text using indented_lines/3.

 structured_comment(-Prefixes:list(codes), -Style) is semidet[private]

Grammar rule version of the above. Avoids the need for conversion.

 separator_line// is semidet[private]

Matches a line like %% SWI or %%%%%%%%%%%%%%%%%%%%%%%%%, etc.

 doc_file_name(+Source:atom, -Doc:atom, +Options:list) is det

Doc is the name of the file for documenting Source.

Arguments:

Source	- Prolog source to be documented
Doc	- the name of the file documenting Source.
Options	- Option list: format(+Format) Output format. One of html or tex

Errors

- permission_error(overwrite, Source)

 doc_file_has_comments(+Source:atom) is semidet

True if we have loaded comments from Source.

 doc_comment(?Objects, -Pos, -Summary:string, -Comment:string) is nondet

True if Comment is the comment describing object. Comment is returned as a string object containing the original from the source-code. Object is one of

• Name/Arity Predicate indicator
• Name//Arity DCG rule indicator. Same as Name/Arity+2
• module(ModuleTitle) Comment appearing in a module.
• Other objects Created by the hook doc_compile_comment/5, e.g., xpce(Class, Kind, Name) for members of xpce classes.

If Object is unbound and multiple objects share the same description, Object is unified with a list of terms described above.

Arguments:

Summary	- First sentence. Normalised spacing.
Comment	- Comment string from the source-code (untranslated)

 doc_signature(?Object, ?Signature:string) is nondet

True when Signature is the signature of Object as provided by the hook prolog:doc_compile_comment/6. Object is qualified as with doc_comment/4.

 process_comments(+Comments:list, +TermPos, +File) is det

 process_comments(+Comments:list, +TermPos, ?Term, +VarNames, +File) is det

Processes comments returned by read_term/3 using the comments option. It creates clauses of the form

• '$mode'(Head, Det)
• '$pldoc'(Id, Pos, Summary, Comment)
• '$pldoc_link'(Id0, Id)

where Id is one of

module(Title)

Generated from /** <module> Title */

Name / Arity

Generated from Name(Arg, ...)

Name // Arity

Generated from Name(Arg, ...)//

Arguments:

Comments	- is a list Pos-Comment returned by read_term/3
TermPos	- is the start-location of the actual term
Term	- is the term read. It is passed to the prolog:doc_compile_comment/6 hook for the last comment before the term.
VarNames	- is a list Name=Var for the variables of Term.
File	- is the file that is being loaded.

 parse_comment(+Comment, +FilePos, -Parsed) is semidet

 parse_comment(+Comment, +FilePos, ?Term, +VarNames, -Parsed) is semidet

True when Comment is a structured comment and Parsed is its parsed representation. Parsed is a list of the following terms:

section(Id, Title, Comment)

Generated from /** <module> Title Comment */ comments.

predicate(PI, Summary, Comment)

Comment for predicate PI

link(FromPI, ToPI)

Indicate that FromPI shares its comment with ToPI. The actual comment is in ToPI.

mode(Head, Determinism)

Mode declaration. Head is a term with Mode(Type) terms and Determinism describes the associated determinism (det, etc.).

object(Object, Summary, Comment)

Comment for some other Object, produced by the hook prolog:doc_compile_comment/6.

signature(Object, Signature)

Signature of Object as a string, produced by the hook prolog:doc_compile_comment/6.

Term is the term that follows Comment and VarNames is a list Name=Var for its variables. Both are passed to prolog:doc_compile_comment/6.

 comment_modes(+Comment, -Modes:list) is semidet

 process_structured_comment(+FilePos, +Comment:string, +Prefixed:list, ?Term, +VarNames, +Style) is det[private]

Proccess a structured comment, adding the documentation facts to the database. This predicate verifies that the comment has not already been loaded.

To be done

- Note that as of version 7.3.12 clauses from a file being reloaded are not wiped before the reloading and therefore we cannot test the clause while reloading a file. Ultimately we need a better test for this.

 comment_warning(+Style, +Error) is failure[private]

Print a warning on structured comments that could not be processed. Since the recommended magic sequence is now %!, we remain silent about comments that start with %%.

 compile_comment(+Comment, +FilePos, +Prefixes, ?Term, +VarNames, -Compiled) is semidet[private]

Compile structured Comment into a list of terms that describe the comment.

See also

- parse_comment/3 for the terms in Compiled.

 doc_clean(+Module) is det

Clean documentation for Module.