[doc] multimap.opa: improve documentation (comments and coercions)

CHANGELOG

stdlib/multimap/multimap.opa

@@ -1,5 +1,5 @@
 /*
-    Copyright © 2011 MLstate
+    Copyright © 2011, 2012 MLstate
 
     This file is part of OPA.
 
@@ -21,32 +21,47 @@
 
 type multimap('a, 'b, 'order) = ordered_map('a, list('b), 'order)
 
+/** Multimap operations with custom order */
 Make_multimap(order) =
 {{
    @private multimap = Map_make(order)
-   empty = multimap.empty
-   add(key, val, map) = set(key, (val +> get(key, map)), map)
-   get(key, map) = default( [], multimap.get(key, map))
-   rem(key, val, map) =
+   empty:multimap = multimap.empty
+   /** add a value [val] for the key [key] in the map [map], preserving old previous binding for [key] */
+   add(key, val, map:multimap):multimap = set(key, [val|get(key, map)], map)
+
+   /** get all value associated to key [key] */
+   get(key, map:multimap) = multimap.get(key, map) ? []
+
+   /** remove, if possible, the more recent value equals to [val] associated with key [key] in [map] */
+   rem(key, val, map:multimap):multimap =
      rec f(li) =
        match li with
        | [] -> []
-       | [hd | tl] -> if Order.equal(hd,val,order) then tl else hd +> f(tl)
+       | [hd | tl] -> if Order.equal(hd,val,order) then tl else [hd|f(tl)]
      v = f(get(key, map))
      set(key, v, map)
-   rem_last(key, map) =
+   /** remove the more recent value associated to [key], fails if no such value exists */
+   rem_last(key, map:multimap):multimap =
      set(key, List.tail(get(key, map)), map)
-   fold(f, map, acc) =
+   /** fold all key value association */
+   fold(f, map:multimap, acc) =
      multimap.fold(
        ( key, val, acc -> List.fold_left(
          (acc, val -> f(key, val, acc)),
          acc,
          val)),
        map, acc)
-   rem_all_val(key, val, map) =
+
+   /** remove, if possible, all values equals to [val] associated with key [key] in [map] */   rem_all_val(key, val, map:multimap):multimap =
      set(key, List.filter((Order.not_equal(val,_,order)), get(key, map) ) , map)
-   rem_all(key, map) = multimap.remove(key, map)
-   set(key, val_list, map) = multimap.add(key, val_list, map)
+   /** remove all values associated to [key] */
+   rem_all(key, map:multimap):multimap = multimap.remove(key, map)
+
+   /** set the complete list [list] of val associated to the [key],
+       the list is ordered from more recent to less recent */
+   set(key, val_list, map:multimap) = multimap.add(key, val_list, map)
+
 }}
 
+/** Multimap operations with default order */
 Multimap = @nonexpansive(Make_multimap(Order.default))