Merge pull request #1656 from aarroyoc/docs-ordsets

Compatible Doclog docs for library(ordsets)

src/lib/ordsets.pl

@@ -54,20 +54,19 @@
 
 :- use_module(library(lists)).
 
-/** <module> Ordered set manipulation
+/** Ordered set manipulation
+
 Ordered sets are lists with unique elements sorted to the standard order
 of terms (see sort/2). Exploiting ordering,   many of the set operations
 can be expressed in order N rather  than N^2 when dealing with unordered
 sets that may contain duplicates. The library(ordsets) is available in a
 number of Prolog implementations. Our  predicates   are  designed  to be
-compatible  with  common  practice   in    the   Prolog  community.  The
-implementation is incomplete and  relies   partly  on  library(oset), an
-older ordered set library distributed  with SWI-Prolog. New applications
-are advised to use library(ordsets).
+compatible  with  common  practice   in    the   Prolog  community.
 Some  of  these  predicates  match    directly   to  corresponding  list
 operations. It is advised to use the  versions from this library to make
 clear you are operating on ordered sets.   An exception is member/2. See
-ord_memberchk/2.
+ord\_memberchk/2.
+
 The ordsets library is based  on  the   standard  order  of  terms. This
 implies it can handle  all  Prolog   terms,  including  variables.  Note
 however, that the ordering is not stable  if   a  term inside the set is
@@ -80,7 +79,7 @@ fresh variable. In other cases one should   cease  using it as an ordset
 because the order it relies on may have been changed.
 */
 
-%!  is_ordset(@Term) is semidet.
+%% is_ordset(@Term) is semidet.
 %
 % True if Term is an ordered set.   All predicates in this library
 % expect ordered sets as input arguments.  Failing to fullfil this
@@ -102,7 +101,7 @@ is_ordset3([H2|T], H) :-
     is_ordset3(T, H2).
 
 
-%!  ord_empty(?List) is semidet.
+%% ord_empty(?List) is semidet.
 %
 % True when List is the  empty   ordered  set. Simply unifies list
 % with the empty list. Not part of Quintus.
@@ -110,18 +109,16 @@ is_ordset3([H2|T], H) :-
 ord_empty([]).
 
 
-%!  ord_seteq(+Set1, +Set2) is semidet.
+%% ord_seteq(+Set1, +Set2) is semidet.
 %
 % True if Set1 and Set2  have  the   same  elements.  As  both are
 % canonical sorted lists, this is the same as ==/2.
-%
-%   @compat sicstus
 
 ord_seteq(Set1, Set2) :-
     Set1 == Set2.
 
 
-%!  list_to_ord_set(+List, -OrdSet) is det.
+%% list_to_ord_set(+List, -OrdSet) is det.
 %
 % Transform a list into an ordered set.  This is the same as
 % sorting the list.
@@ -130,7 +127,7 @@ list_to_ord_set(List, Set) :-
     sort(List, Set).
 
 
-%!  ord_intersect(+Set1, +Set2) is semidet.
+%% ord_intersect(+Set1, +Set2) is semidet.
 %
 % True if both ordered sets have a non-empty intersection.
 
@@ -148,31 +145,29 @@ ord_intersect__(>, H1, T1,  _H2, T2) :-
     ord_intersect_(T2, H1, T1).
 
 
-%!  ord_disjoint(+Set1, +Set2) is semidet.
+%% ord_disjoint(+Set1, +Set2) is semidet.
 %
 % True if Set1 and Set2  have  no   common  elements.  This is the
-%   negation of ord_intersect/2.
+% negation of ord\_intersect/2.
 
 ord_disjoint(Set1, Set2) :-
     \+ ord_intersect(Set1, Set2).
 
 
-%!  ord_intersect(+Set1, +Set2, -Intersection)
+%% ord_intersect(+Set1, +Set2, -Intersection)
 %
 % Intersection  holds  the  common  elements  of  Set1  and  Set2.
 %
-%   @deprecated Use ord_intersection/3
+% This predicate is **deprecated**. Use ord\_intersection/3
 
 ord_intersect(Set1, Set2, Intersection) :-
     oset_int(Set1, Set2, Intersection).
 
 
-%!  ord_intersection(+PowerSet, -Intersection)
+%% ord_intersection(+PowerSet, -Intersection)
 %
 % Intersection of a powerset. True when Intersection is an ordered
 % set holding all elements common to all sets in PowerSet.
-%
-%   @compat sicstus
 
 ord_intersection(PowerSet, Intersection) :-
     key_by_length(PowerSet, Pairs),
@@ -190,10 +185,10 @@ l_int([_-H|T], S0, S) :-
     l_int(T, S1, S).
 
 
-%!  ord_intersection(+Set1, +Set2, -Intersection) is det.
+%% ord_intersection(+Set1, +Set2, -Intersection) is det.
 %
 % Intersection holds the common elements of Set1 and Set2.  Uses
-%   ord_disjoint/2 if Intersection is bound to `[]` on entry.
+% ord\_disjoint/2 if Intersection is bound to `[]` on entry.
 
 ord_intersection(Set1, Set2, Intersection) :-
     (   Intersection == []
@@ -202,13 +197,11 @@ ord_intersection(Set1, Set2, Intersection) :-
     ).
 
 
-%!  ord_intersection(+Set1, +Set2, ?Intersection, ?Difference) is det.
+%% ord_intersection(+Set1, +Set2, ?Intersection, ?Difference) is det.
 %
 % Intersection  and  difference   between    two   ordered   sets.
 % Intersection is the intersection between   Set1  and Set2, while
-%   Difference is defined by ord_subtract(Set2, Set1, Difference).
-%
-%   @see ord_intersection/3 and ord_subtract/3.
+% Difference is defined by ord\_subtract(Set2, Set1, Difference).
 
 ord_intersection([], L, [], L) :- !.
 ord_intersection([_|_], [], [], []) :- !.
@@ -224,35 +217,35 @@ ord_intersection2(>, H1, T1, H2, T2, Intersection, [H2|HDiff]) :-
     ord_intersection([H1|T1], T2, Intersection, HDiff).
 
 
-%!  ord_add_element(+Set1, +Element, ?Set2) is det.
+%% ord_add_element(+Set1, +Element, ?Set2) is det.
 %
 % Insert  an  element  into  the  set.    This   is  the  same  as
-%   ord_union(Set1, [Element], Set2).
+% ord\_union(Set1, [Element], Set2).
 
 ord_add_element(Set1, Element, Set2) :-
     oset_addel(Set1, Element, Set2).
 
 
-%!  ord_del_element(+Set, +Element, -NewSet) is det.
+%% ord_del_element(+Set, +Element, -NewSet) is det.
 %
 % Delete an element from an  ordered  set.   This  is  the same as
-%   ord_subtract(Set, [Element], NewSet).
+% ord\_subtract(Set, [Element], NewSet).
 
 ord_del_element(Set, Element, NewSet) :-
     oset_delel(Set, Element, NewSet).
 
 
-%!  ord_selectchk(+Item, ?Set1, ?Set2) is semidet.
+%% ord_selectchk(+Item, ?Set1, ?Set2) is semidet.
 %
 % Selectchk/3,  specialised  for  ordered  sets.    Is  true  when
 % select(Item, Set1, Set2) and Set1, Set2   are  both sorted lists
 % without duplicates. This implementation is only expected to work
 % for Item ground and either Set1 or Set2 ground. The "chk" suffix
 % is meant to remind you of   memberchk/2,  which also expects its
-%   first  argument  to  be  ground.    ord_selectchk(X,  S,  T)  =>
-%   ord_memberchk(X, S) & \+ ord_memberchk(X, T).
+% first  argument  to  be  ground.    ord\_selectchk(X,  S,  T)  =>
+% ord\_memberchk(X, S) & \\+ ord\_memberchk(X, T).
 %
-%   @author Richard O'Keefe
+% Author: Richard O'Keefe
 
 ord_selectchk(Item, [X|Set1], [X|Set2]) :-
     X @< Item,
@@ -266,19 +259,19 @@ ord_selectchk(Item, [Item|Set1], Set1) :-
     ).
 
 
-%!  ord_memberchk(+Element, +OrdSet) is semidet.
+%% ord_memberchk(+Element, +OrdSet) is semidet.
 %
 % True if Element is a member of   OrdSet, compared using ==. Note
 % that _enumerating_ elements of an ordered  set can be done using
 % member/2.
 %
-%   Some Prolog implementations also provide  ord_member/2, with the
-%   same semantics as ord_memberchk/2.  We   believe  that  having a
-%   semidet ord_member/2 is unacceptably inconsistent with the *_chk
-%   convention.  Portable  code  should    use   ord_memberchk/2  or
+% Some Prolog implementations also provide  ord\_member/2, with the
+% same semantics as ord\_memberchk/2.  We   believe  that  having a
+% semidet ord\_member/2 is unacceptably inconsistent with the \*\_chk
+% convention.  Portable  code  should    use   ord\_memberchk/2  or
 % member/2.
 %
-%   @author Richard O'Keefe
+% Author: Richard O'Keefe
 
 ord_memberchk(Item, [X1,X2,X3,X4|Xs]) :-
     !,
@@ -303,7 +296,7 @@ ord_memberchk(Item, [X1]) :-
     Item == X1.
 
 
-%!  ord_subset(+Sub, +Super) is semidet.
+%% ord_subset(+Sub, +Super) is semidet.
 %
 % Is true if all elements of Sub are in Super
 
@@ -319,7 +312,7 @@ ord_subset_(=, _, T1, T2) :-
     ord_subset(T1, T2).
 
 
-%!  ord_subtract(+InOSet, +NotInOSet, -Diff) is det.
+%% ord_subtract(+InOSet, +NotInOSet, -Diff) is det.
 %
 % Diff is the set holding all elements of InOSet that are not in
 % NotInOSet.
@@ -328,13 +321,11 @@ ord_subtract(InOSet, NotInOSet, Diff) :-
     oset_diff(InOSet, NotInOSet, Diff).
 
 
-%!  ord_union(+SetOfSets, -Union) is det.
+%% ord_union(+SetOfSets, -Union) is det.
 %
 % True if Union is the  union  of   all  elements  in the superset
 % SetOfSets. Each member of SetOfSets must  be an ordered set, the
 % sets need not be ordered in any way.
-%
-%   @author Copied from YAP, probably originally by Richard O'Keefe.
 
 ord_union([], []).
 ord_union([Set|Sets], Union) :-
@@ -355,7 +346,7 @@ ord_union_all(N, Sets0, Union, Sets) :-
     ).
 
 
-%!  ord_union(+Set1, +Set2, ?Union) is det.
+%% ord_union(+Set1, +Set2, ?Union) is det.
 %
 % Union is the union of Set1 and Set2
 
@@ -363,10 +354,10 @@ ord_union(Set1, Set2, Union) :-
     oset_union(Set1, Set2, Union).
 
 
-%!  ord_union(+Set1, +Set2, -Union, -New) is det.
+%% ord_union(+Set1, +Set2, -Union, -New) is det.
 %
-%   True iff ord_union(Set1, Set2, Union) and
-%   ord_subtract(Set2, Set1, New).
+% True iff ord\_union(Set1, Set2, Union) and
+% ord\_subtract(Set2, Set1, New).
 
 ord_union([], Set2, Set2, Set2).
 ord_union([H|T], Set2, Union, New) :-
@@ -390,7 +381,7 @@ ord_union_2([H|T], H2, T2, Union, New) :-
     ord_union(Order, H, T, H2, T2, Union, New).
 
 
-%!  ord_symdiff(+Set1, +Set2, ?Difference) is det.
+%% ord_symdiff(+Set1, +Set2, ?Difference) is det.
 %
 % Is true when Difference is the  symmetric difference of Set1 and
 % Set2. I.e., Difference contains all elements that are not in the
@@ -398,18 +389,14 @@ ord_union_2([H|T], H2, T2, Union, New) :-
 % sequence below (but the actual   implementation  requires only a
 % single scan).
 %
-%     ==
 %     ord_union(Set1, Set2, Union),
 %     ord_intersection(Set1, Set2, Intersection),
 %     ord_subtract(Union, Intersection, Difference).
-%     ==
 %
 %   For example:
 %
-%     ==
 %     ?- ord_symdiff([1,2], [2,3], X).
 %     X = [1,3].
-%     ==
 
 ord_symdiff([], Set2, Set2).
 ord_symdiff([H1|T1], Set2, Difference) :-
@@ -457,7 +444,7 @@ ord_symdiff(>, H1, T1, H2, Set2, [H2|Difference]) :-
 */
 
 
-/** <module> Ordered set manipulation
+/* Ordered set manipulation
 
 This library defines set operations on sets represented as ordered
 lists.