PublicShow sourcedoc_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
Source prolog:predicate_summary(+PI, -Summary) is semidet[multifile]
Provide predicate summaries to the XPCE class prolog_predicate, used by the IDE tools.
Source 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.
Source 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)
Source doc_file_has_comments(+Source:atom) is semidet
True if we have loaded comments from Source.
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)
Source 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.
Source 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.).
Source comment_modes(+Comment, -Modes:list) is semidet
Source doc_clean(+Module) is det
Clean documentation for Module.