From: Markus Triska <triska@metalevel.at>
Date: Wed, 25 Jan 2023 23:36:05 +0000 (+0100)
Subject: DOC: initial documentation for library(pairs) in DocLog format
X-Git-Tag: v0.9.2~213^2
X-Git-Url: https://git.sagredo.dev/?a=commitdiff_plain;h=996496c3f5373000780b5155ca974ff8102235a8;p=scryer-prolog.git

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

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) :-