7.14 Example Usage Comments

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:

C-c C-%

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.