From: Markus Triska <triska@metalevel.at>
Date: Tue, 24 Jan 2023 23:19:14 +0000 (+0100)
Subject: DOC: add DocLog documentation for library(debug)
X-Git-Tag: v0.9.2~219^2
X-Git-Url: https://git.sagredo.dev/?a=commitdiff_plain;h=64be8e0fba06d15ad56dd652703c9de853cd8fe8;p=scryer-prolog.git

DOC: add DocLog documentation for library(debug)
---

diff --git a/src/lib/debug.pl b/src/lib/debug.pl
index ab84f15b..e237d8e1 100644
--- a/src/lib/debug.pl
+++ b/src/lib/debug.pl
@@ -1,4 +1,22 @@
-% Source: https://stackoverflow.com/a/30791637
+/** Declarative debugging.
+
+  This library provides three predicates with associated operators.
+  The operators can be placed in front of goals to debug Prolog
+  programs.
+
+  Of these predicates, the most frequently used is `(*)/1`, with
+  associated prefix operator `*` (star). Placing `*` in front of a
+  goal means to _generalize away_ the goal. `* Goal` acts as if `Goal`
+  did not appear at all in the source code. It is declaratively
+  equivalent to _commenting out_ the goal, and easier to write,
+  because `*` can also be placed in front of the last goal in a clause
+  without any additional changes.
+
+  Source: [https://stackoverflow.com/a/30791637](https://stackoverflow.com/a/30791637)
+
+*/
+
+
 
 :- module(debug, [
     op(900, fx, $),
@@ -15,12 +33,25 @@
 :- meta_predicate $(0).
 :- meta_predicate $-(0).
 
+%% $-(Goal)
+%
+%  Portray exceptions thrown by Goal.
+
 $-(G_0) :-
    catch(G_0, Ex, ( portray_clause(exception:Ex:G_0), throw(Ex) ) ).
 
+%% $(Goal)
+%
+%  Provide a _trace_ for calls of Goal.
+
 $(G_0) :-
    portray_clause(call:G_0),
    $-G_0,
    portray_clause(exit:G_0).
 
+%% *(Goal)
+%
+%  Generalize away Goal.
+
+
 *(_).