7.13 Documenting Predicates ¶

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.

C-c C-d ¶

Insert ‘PlDoc’ documentation comment for the predicate at or above point (sweeprolog-document-predicate-at-point).

User Option: sweeprolog-read-predicate-documentation-function ¶

Function to use for determining the initial contents of documentation comments that you insert with sweeprolog-document-predicate-at-point.

Function: sweeprolog-read-predicate-documentation-default-function ¶

Prompt and read from the minibuffer the argument modes, determinism specification and initial summary of the given predicate.

Function: sweeprolog-read-predicate-documentation-with-holes ¶

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.