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.

 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.

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)

 process_comments(+Comments:list, +TermPos, +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
File	- is the file that is being loaded.

 parse_comment(+Comment, +FilePos, -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.).

 process_structured_comment(+FilePos, +Comment:string, +Prefixed:list, +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, -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.