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.).
- comment_modes(+Comment, -Modes:list) is semidet
- 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.
- doc_clean(+Module) is det
- Clean documentation for Module.