Beyond documenting your code with ‘PlDoc’ comments as described in Documenting Predicates, you may want to have comments in your source code that demonstrate example usage of some predicate or another. Creating such comments usually involves posting queries in a Prolog top-level, copying the queries and their results into the relevant source code buffer, and formatting them as comments. Sweep provides the following command to streamline this process:
Start a new top-level for recording example usage. When you finish
interacting with the top-level its contents are formatted as a comment
in the buffer and position where you invoked this command
(sweeprolog-make-example-usage-comment).
The command sweeprolog-make-example-usage-comment, bound to
C-c C-% in Sweep Prolog mode buffers, creates and switches to a
new top-level buffer for recording example usage that you want to
demonstrate. The example usage top-level is a regular top-level
buffer (see The Prolog Top-level), except that it’s tied to the
specific position in the source buffer where you invoke this command.
You can post queries in the example usage top-level and edit it
freely, then type C-c C-q in to quit the top-level buffer and
format its contents as a comment in the source buffer.
You can have multiple example usage top-levels for different parts of your code at the same time. To display the source position where you created a certain usage example top-level buffer by, type C-c C-b in that buffer.