fixup! Polish documentation for the sets modules

lib/stdlib/src/gb_sets.erl

@@ -697,8 +697,21 @@ merge(Smaller, Larger) ->
     {Key, Smaller, Larger1}.
 
 -doc """
-Returns `{Element, Set2}`, where `Element` is the smallest element in `Set1`,
-and `Set2` is this set with `Element` deleted. Assumes that `Set1` is not empty.
+Returns `{Element, Set2}`, where `Element` is the smallest element in
+`Set1`, and `Set2` is this set with `Element` deleted.
+
+Assumes that `Set1` is not empty.
+
+## Examples
+
+```erlang
+> S0 = gb_sets:from_list([a,b,c]).
+> {Smallest,S1} = gb_sets:take_smallest(S0).
+> Smallest.
+a
+> gb_sets:to_list(S1).
+[b,c]
+```
 """.
 -spec take_smallest(Set1) -> {Element, Set2} when
       Set1 :: set(Element),
@@ -714,7 +727,19 @@ take_smallest1({Key, Smaller, Larger}) ->
     {Key1, Smaller1} = take_smallest1(Smaller),
     {Key1, {Key, Smaller1, Larger}}.
 
--doc "Returns the smallest element in `Set`. Assumes that `Set` is not empty.".
+-doc """
+Returns the smallest element in `Set`.
+
+Assumes that `Set` is not empty.
+
+## Examples
+
+```erlang
+> S = gb_sets:from_list([a,b,c]).
+> gb_sets:smallest(S).
+a
+```
+""".
 -spec smallest(Set) -> Element when
       Set :: set(Element).
 
@@ -727,8 +752,21 @@ smallest_1({_Key, Smaller, _Larger}) ->
     smallest_1(Smaller).
 
 -doc """
-Returns `{Element, Set2}`, where `Element` is the largest element in `Set1`, and
-`Set2` is this set with `Element` deleted. Assumes that `Set1` is not empty.
+Returns `{Element, Set2}`, where `Element` is the largest element in
+`Set1`, and `Set2` is this set with `Element` deleted.
+
+Assumes that `Set1` is not empty.
+
+## Examples
+
+```erlang
+> S0 = gb_sets:from_list([a,b,c]).
+> {Largest,S1} = gb_sets:take_largest(S0).
+> Largest.
+c
+> gb_sets:to_list(S1).
+[a,b]
+```
 """.
 -spec take_largest(Set1) -> {Element, Set2} when
       Set1 :: set(Element),
@@ -744,7 +782,19 @@ take_largest1({Key, Smaller, Larger}) ->
     {Key1, Larger1} = take_largest1(Larger),
     {Key1, {Key, Smaller, Larger1}}.
 
--doc "Returns the largest element in `Set`. Assumes that `Set` is not empty.".
+-doc """
+Returns the largest element in `Set`.
+
+Assumes that `Set` is not empty.
+
+## Examples
+
+```erlang
+> S = gb_sets:from_list([a,b,c]).
+> gb_sets:largest(S).
+c
+```
+""".
 -spec largest(Set) -> Element when
       Set :: set(Element).