Merge pull request #1646 from aarroyoc/docs-assoc

Compatible Doclog docs for library(assoc)

src/lib/assoc.pl

@@ -54,25 +54,24 @@
 
 :- use_module(library(lists)).
 
-/** <module> Binary associations
+/** Binary associations
 
 Assocs are Key-Value associations implemented as  a balanced binary tree
 (AVL tree).
 
-@see            library(pairs), library(rbtrees)
+Authors: R.A.O'Keefe, L.Damas, V.S.Costa and Jan Wielemaker
-@author         R.A.O'Keefe, L.Damas, V.S.Costa and Jan Wielemaker
 */
 
 :- meta_predicate map_assoc(1, ?).
 :- meta_predicate map_assoc(2, ?, ?).
 
-%!  empty_assoc(?Assoc) is semidet.
+%% empty_assoc(?Assoc) is semidet.
 %
 % Is true if Assoc is the empty association list.
 
 empty_assoc(t).
 
-%!  assoc_to_list(+Assoc, -Pairs) is det.
+%% assoc_to_list(+Assoc, -Pairs) is det.
 %
 % Translate Assoc to a list Pairs of Key-Value pairs.  The keys
 % in Pairs are sorted in ascending order.
@@ -86,7 +85,7 @@ assoc_to_list(t(Key,Val,_,L,R), List, Rest) :-
 assoc_to_list(t, List, List).
 
 
-%!  assoc_to_keys(+Assoc, -Keys) is det.
+%% assoc_to_keys(+Assoc, -Keys) is det.
 %
 % True if Keys is the list of keys   in Assoc. The keys are sorted
 % in ascending order.
@@ -100,7 +99,7 @@ assoc_to_keys(t(Key,_,_,L,R), List, Rest) :-
 assoc_to_keys(t, List, List).
 
 
-%!  assoc_to_values(+Assoc, -Values) is det.
+%% assoc_to_values(+Assoc, -Values) is det.
 %
 % True if Values is the  list  of   values  in  Assoc.  Values are
 % ordered in ascending  order  of  the   key  to  which  they were
@@ -114,7 +113,7 @@ assoc_to_values(t(_,Value,_,L,R), List, Rest) :-
     assoc_to_values(R, More, Rest).
 assoc_to_values(t, List, List).
 
-%!  is_assoc(+Assoc) is semidet.
+%% is_assoc(+Assoc) is semidet.
 %
 % True if Assoc is an association list. This predicate checks
 % that the structure is valid, elements are in order, and tree
@@ -151,12 +150,10 @@ balance(=,-).
 balance(<,<).
 balance(>,>).
 
-%!  gen_assoc(?Key, +Assoc, ?Value) is nondet.
+%% gen_assoc(?Key, +Assoc, ?Value) is nondet.
 %
 % True if Key-Value is an association in Assoc. Enumerates keys in
 % ascending order on backtracking.
-%
-%   @see get_assoc/3.
 
 gen_assoc(Key, Assoc, Value) :-
     (   ground(Key)
@@ -171,11 +168,11 @@ gen_assoc_(Key, t(_,_,_,_,R), Val) :-
     gen_assoc_(Key, R, Val).
 
 
-%!  get_assoc(+Key, +Assoc, -Value) is semidet.
+%% get_assoc(+Key, +Assoc, -Value) is semidet.
 %
 % True if Key-Value is an association in Assoc.
 %
-%   @error type_error(assoc, Assoc) if Assoc is not an association list.
+% Throws error: type_error(assoc, Assoc) if Assoc is not an association list.
 
 get_assoc(Key, Assoc, Val) :-
     must_be(assoc, Assoc),
@@ -201,7 +198,7 @@ get_assoc(>, Key, _, _, Tree, Val) :-
 % :- endif.
 
 
-%!  get_assoc(+Key, +Assoc0, ?Val0, ?Assoc, ?Val) is semidet.
+%% get_assoc(+Key, +Assoc0, ?Val0, ?Assoc, ?Val) is semidet.
 %
 % True if Key-Val0 is in Assoc0 and Key-Val is in Assoc.
 
@@ -216,12 +213,12 @@ get_assoc(>, Key, V, L, R, Val, V, L, NR, NVal) :-
     get_assoc(Key, R, Val, NR, NVal).
 
 
-%!  list_to_assoc(+Pairs, -Assoc) is det.
+%% list_to_assoc(+Pairs, -Assoc) is det.
 %
 % Create an association from a list Pairs of Key-Value pairs. List
 % must not contain duplicate keys.
 %
-%   @error domain_error(unique_key_pairs, List) if List contains duplicate keys
+% Throws error: domain_error(unique_key_pairs, List) if List contains duplicate keys
 
 list_to_assoc(List, Assoc) :-
     (  List = [] -> Assoc = t
@@ -246,13 +243,13 @@ list_to_assoc(N, List, More, Depth, t(K,V,Balance,L,R)) :-
     compare(B, RDepth, LDepth),
     balance(B, Balance).
 
-%!  ord_list_to_assoc(+Pairs, -Assoc) is det.
+%% ord_list_to_assoc(+Pairs, -Assoc) is det.
 %
 % Assoc is created from an ordered list Pairs of Key-Value
 % pairs. The pairs must occur in strictly ascending order of
 % their keys.
 %
-%   @error domain_error(key_ordered_pairs, List) if pairs are not ordered.
+% Throws error: domain_error(key_ordered_pairs, List) if pairs are not ordered.
 
 ord_list_to_assoc(Sorted, Assoc) :-
     (  Sorted = [] -> Assoc = t
@@ -263,7 +260,7 @@ ord_list_to_assoc(Sorted, Assoc) :-
            )
     ).
 
-%!  ord_pairs(+Pairs) is semidet
+%% ord_pairs(+Pairs) is semidet
 %
 % True if Pairs is a list of Key-Val pairs strictly ordered by key.
 
@@ -274,7 +271,7 @@ ord_pairs([K-_V|Rest], K0) :-
     K0 @< K,
     ord_pairs(Rest, K).
 
-%!  map_assoc(:Pred, +Assoc) is semidet.
+%% map_assoc(:Pred, +Assoc) is semidet.
 %
 % True if Pred(Value) is true for all values in Assoc.
 
@@ -287,7 +284,7 @@ map_assoc_(t(_,Val,_,L,R), Pred) :-
     call(Pred, Val),
     map_assoc_(R, Pred).
 
-%!  map_assoc(:Pred, +Assoc0, ?Assoc) is semidet.
+%% map_assoc(:Pred, +Assoc0, ?Assoc) is semidet.
 %
 % Map corresponding values. True if Assoc is Assoc0 with Pred
 % applied to all corresponding pairs of of values.
@@ -302,7 +299,7 @@ map_assoc_(t(Key,Val,B,L0,R0), Pred, t(Key,Ans,B,L1,R1)) :-
     map_assoc_(R0, Pred, R1).
 
 
-%!  max_assoc(+Assoc, -Key, -Value) is semidet.
+%%  max_assoc(+Assoc, -Key, -Value) is semidet.
 %
 % True if Key-Value is in Assoc and Key is the largest key.
 
@@ -314,7 +311,7 @@ max_assoc(t(K,V,_,_,R), _, _, Key, Val) :-
     max_assoc(R, K, V, Key, Val).
 
 
-%!  min_assoc(+Assoc, -Key, -Value) is semidet.
+%% min_assoc(+Assoc, -Key, -Value) is semidet.
 %
 % True if Key-Value is in assoc and Key is the smallest key.
 
@@ -326,7 +323,7 @@ min_assoc(t(K,V,_,L,_), _, _, Key, Val) :-
     min_assoc(L, K, V, Key, Val).
 
 
-%!  put_assoc(+Key, +Assoc0, +Value, -Assoc) is det.
+%% put_assoc(+Key, +Assoc0, +Value, -Assoc) is det.
 %
 % Assoc is Assoc0, except that Key is associated with
 % Value. This can be used to insert and change associations.
@@ -361,7 +358,7 @@ table(<      , right   , -      , no        , no    ) :- !.
 table(>      , left    , -      , no        , no    ) :- !.
 table(>      , right   , -      , no        , yes   ) :- !.
 
-%!  del_min_assoc(+Assoc0, ?Key, ?Val, -Assoc) is semidet.
+%% del_min_assoc(+Assoc0, ?Key, ?Val, -Assoc) is semidet.
 %
 % True if Key-Value  is  in  Assoc0   and  Key  is  the smallest key.
 % Assoc is Assoc0 with Key-Value   removed. Warning: This will
@@ -375,7 +372,7 @@ del_min_assoc(t(K,V,B,L,R), Key, Val, NewTree, Changed) :-
     del_min_assoc(L, Key, Val, NewL, LeftChanged),
     deladjust(LeftChanged, t(K,V,B,NewL,R), left, NewTree, Changed).
 
-%!  del_max_assoc(+Assoc0, ?Key, ?Val, -Assoc) is semidet.
+%% del_max_assoc(+Assoc0, ?Key, ?Val, -Assoc) is semidet.
 %
 % True if Key-Value  is  in  Assoc0   and  Key  is  the greatest key.
 % Assoc is Assoc0 with Key-Value   removed. Warning: This will
@@ -389,7 +386,7 @@ del_max_assoc(t(K,V,B,L,R), Key, Val, NewTree, Changed) :-
     del_max_assoc(R, Key, Val, NewR, RightChanged),
     deladjust(RightChanged, t(K,V,B,L,NewR), right, NewTree, Changed).
 
-%!  del_assoc(+Key, +Assoc0, ?Value, -Assoc) is semidet.
+%% del_assoc(+Key, +Assoc0, ?Value, -Assoc) is semidet.
 %
 % True if Key-Value is  in  Assoc0.   Assoc  is  Assoc0 with
 % Key-Value removed.