From 996496c3f5373000780b5155ca974ff8102235a8 Mon Sep 17 00:00:00 2001
From: Markus Triska <triska@metalevel.at>
Date: Thu, 26 Jan 2023 00:36:05 +0100
Subject: [PATCH] DOC: initial documentation for library(pairs) in DocLog
 format

---
 src/lib/pairs.pl | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/lib/pairs.pl b/src/lib/pairs.pl
index 8ed74777..17216b49 100644
--- 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) :-
-- 
2.54.0