DOC: convert library(si) documentation to DocLog format
-/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- 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,
