From: Markus Triska <triska@metalevel.at>
Date: Wed, 25 Jan 2023 22:27:45 +0000 (+0100)
Subject: DOC: convert library(si) documentation to DocLog format
X-Git-Tag: v0.9.2~208^2
X-Git-Url: https://git.sagredo.dev/?a=commitdiff_plain;h=7f8f137aa0214573703896a8ab1d065b59d6c753;p=scryer-prolog.git

DOC: convert library(si) documentation to DocLog format
---

diff --git a/src/lib/si.pl b/src/lib/si.pl
index d697c8a8..a1705343 100644
--- a/src/lib/si.pl
+++ b/src/lib/si.pl
@@ -1,28 +1,36 @@
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
-   Safe type tests
-   ===============
+/** Safe type tests.
 
-   "si" stands for "sufficiently instantiated".
+   "si" stands for "sufficiently instantiated". It can also be read as
+   "safe inference", so possibly also other predicates are candidates
+   for this library.
 
-   These predicates:
+   A safe type test:
 
-    - throw instantiation errors if the argument is
+    - throws an *instantiation error* if the argument is
       not sufficiently instantiated to make a sound decision
-    - succeed if the argument is of the specified type
-    - fail otherwise.
+    - *succeeds* if the argument is of the specified type
+    - *fails* otherwise.
 
-   For instance, atom_si(A) yields an *instantiation error* if A is a
+   For instance, `atom_si(A)` yields an *instantiation error* if `A` is a
    variable. This is logically sound, since in that case the argument
    is not sufficiently instantiated to make any decision.
 
-   The definitions are taken from:
-
-       https://stackoverflow.com/questions/27306453/safer-type-tests-in-prolog
-
-   "si" can also be read as "safe inference", so possibly also other
-   predicates are candidates for this library.
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+   The definitions are taken from [Safer type tests in Prolog](https://stackoverflow.com/questions/27306453/safer-type-tests-in-prolog).
+
+   Examples:
+
+```
+?- chars_si(Cs).
+   error(instantiation_error,list_si/1).
+?- chars_si([h|Cs]).
+   error(instantiation_error,list_si/1).
+?- chars_si("hello").
+   true.
+?- chars_si(hello).
+   false.
+```
+*/
 
 :- module(si, [atom_si/1,
                integer_si/1,