SWI-Prolog predicates can be documented with specially structured comments placed above the predicate definition, which are processed by the ‘PlDoc’ source documentation system. Emacs comes with many useful commands specifically intended for working with comments in programming languages, which apply also to writing ‘PlDoc’ comments for Prolog predicates. For an overview of the relevant standard Emacs commands, see (emacs)Comment Commands.
Insert ‘PlDoc’ documentation comment for the predicate at or
above point (sweeprolog-document-predicate-at-point
).
Function to use for determining the initial contents of documentation
comments that you insert with
sweeprolog-document-predicate-at-point
.
Prompt and read from the minibuffer the argument modes, determinism specification and initial summary of the given predicate.
Use holes for the initial documentation of the given predicate.
Sweep also includes a dedicated command called
sweeprolog-document-predicate-at-point
for interactively
creating ‘PlDoc’ comments for predicates in
sweeprolog-mode
buffers. This command, bound by default to
C-c C-d, finds the beginning of the predicate definition under
or right above the current cursor location, and inserts a formatted
‘PlDoc’ comment. This command fills in initial argument modes,
determinism specification, and optionally a summary line for the
documented predicate. There are different ways in which
sweeprolog-document-predicate-at-point
can obtain the needed
initial documentation information, depending on the value of the user
option sweeprolog-read-predicate-documentation-function
which
specifies a function to retrieve this information. The default
function prompts you to insert the parameters one by one via the
minibuffer. Alternatively, you can use holes (see Holes) for the
predicate’s argument modes and determinism specifiers by setting this
option to sweeprolog-read-predicate-documentation-with-holes
,
as follows:
(setq sweeprolog-read-predicate-documentation-function #'sweeprolog-read-predicate-documentation-with-holes)
sweeprolog-document-predicate-at-point
leaves the cursor at the
end of the newly inserted documentation comment for you to extend or
edit it as you see fit. To add another comment line, use M-j
(default-indent-new-line
) which starts a new line with the
comment prefix filled in. Emacs has other powerful built-in features
for working with comments in code buffers that you can leverage to
edit ‘PlDoc’ comments—See (emacs)Comments, for the full
details. Furthermore you can make use of the rich support Emacs
provides for editing natural language text when working on
‘PlDoc’ comments. For example, to nicely format a paragraph of
text, use M-q (fill-paragraph
). Many useful commands for
editing text are documented in (emacs)Text, which see.
For more information about ‘PlDoc’ and source documentation in SWI-Prolog, see the PlDoc manual.