DOC: initial documentation for library(pairs) in DocLog format

diff --git a/src/lib/pairs.pl b/src/lib/pairs.pl
index 8ed7477752ea98ec87353cba50bb766b622e343e..17216b4905862e3def9da1b69de9f9106d783cd9 100644 (file)
--- a/src/lib/pairs.pl
+++ b/src/lib/pairs.pl
@@ -1,3 +1,10 @@
+/** Reasoning about pairs.
+
+    Pairs are Prolog terms with principal functor `(-)/2`. A pair
+    often has the form `Key-Value`. The predicates of this library
+    relate pairs to keys and values.
+*/
+
 :- module(pairs, [pairs_keys_values/3,
                  pairs_keys/2,
                  pairs_values/2,
@@ -7,12 +14,25 @@
 
 :- meta_predicate map_list_to_pairs(2, ?, ?).
 
+%% pairs_keys_values(?Pairs, ?Keys, ?Values)
+%
+%  The first argument is a list of Pairs, the second the corresponding
+%  Keys, and the third argument the corresponding values.
+
 pairs_keys_values([], [], []).
 pairs_keys_values([A-B|ABs], [A|As], [B|Bs]) :-
         pairs_keys_values(ABs, As, Bs).
 
+%% pairs_keys(?Pairs, ?Keys)
+%
+%  Same as `pairs_keys_values(Pairs, Keys, _)`.
+
 pairs_keys(Ps, Ks) :- pairs_keys_values(Ps, Ks, _).
 
+%% pairs_values(?Pairs, ?Values)
+%
+%  Same as `pairs_keys_values(Pairs, _, Values)`.
+
 pairs_values(Ps, Vs) :- pairs_keys_values(Ps, _, Vs).
 
 map_list_to_pairs(Pred, Ls, Ps) :-