DOC: add DocLog documentation for library(debug)

diff --git a/src/lib/debug.pl b/src/lib/debug.pl
index ab84f15b7c4ddff0e4d32e912949a2e4d4ba0003..e237d8e196fdfabbee4f8acd0df798fa1bbf76a3 100644 (file)
--- 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.
+
+
 *(_).