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

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

diff --git a/src/lib/diag.pl b/src/lib/diag.pl
index 0fa3896f..636ed0a4 100644
--- 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) ->