DOC: add DocLog documentation for library(diag)

diff --git a/src/lib/diag.pl b/src/lib/diag.pl
index 0fa3896f90759537bdda7bc23d7111a6f0b7c0dd..636ed0a4c711fdd4fc45cc95e219f5b9d5f68847 100644 (file)
--- a/src/lib/diag.pl
+++ b/src/lib/diag.pl
@@ -1,7 +1,46 @@
 :- module(diag, [wam_instructions/2]).
 
+/** Diagnostics library
+
+  The predicate `wam_instructions/2` _decompiles_ a predicate so that
+  we can inspect its Warren Abstract Machine (WAM) instructions.
+  In this way, we can verify and reason about compiled programs,
+  and detect opportunities for optimization.
+
+  For example, we have:
+
+```
+?- use_module(library(lists)).
+   true.
+?- use_module(library(diag)).
+   true.
+?- use_module(library(format)).
+   true.
+?- wam_instructions(append/3, Is),
+   maplist(portray_clause, Is).
+switch_on_term(1,external(1),external(2),external(6),fail).
+try_me_else(4).
+get_constant(level(shallow),[],x(1)).
+get_value(x(2),3).
+proceed.
+trust_me(0).
+get_list(level(shallow),x(1)).
+unify_variable(x(4)).
+unify_variable(x(1)).
+get_list(level(shallow),x(3)).
+unify_value(x(4)).
+unify_variable(x(3)).
+execute(append,3).
+   Is = [switch_on_term(1,external(1),external(2),external(6),fail)|...].
+```
+*/
+
+
 :- use_module(library(error)).
 
+%% wam_instructions(+PI, -Instrs)
+%
+%  _Instrs_ are the WAM instructions corresponding to predicate indicator _PI_.
 
 wam_instructions(Clause, Listing) :-
     (  nonvar(Clause) ->