From f50846209b496671130ba303cccf6aa5e04d706c Mon Sep 17 00:00:00 2001
From: Simon Cruanes <simon.cruanes.2007@m4x.org>
Date: Fri, 12 Jun 2015 17:11:05 +0200
Subject: [PATCH] add more doc and functions to CCGraph

---
 src/data/CCGraph.ml  | 20 ++++++++++++++++++--
 src/data/CCGraph.mli | 22 +++++++++++++++++++++-
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/src/data/CCGraph.ml b/src/data/CCGraph.ml
index ad643387..72781d08 100644
--- a/src/data/CCGraph.ml
+++ b/src/data/CCGraph.ml
@@ -646,7 +646,13 @@ module type MAP = sig
 
   val remove_edge : vertex -> vertex -> t -> t
 
+  val add : vertex -> t -> t
+  (** Add a vertex, possibly with no outgoing edge *)
+
   val remove : vertex -> t -> t
+  (** Remove the vertex and all its outgoing edges.
+      Edges that point to the vertex are {b NOT} removed, they must be
+      manually removed with {!remove_edge} *)
 
   val union : t -> t -> t
 
@@ -656,10 +662,14 @@ module type MAP = sig
 
   val of_list : (vertex * vertex) list -> t
 
+  val add_list : (vertex * vertex) list -> t -> t
+
   val to_list : t -> (vertex * vertex) list
 
   val of_seq : (vertex * vertex) sequence -> t
 
+  val add_seq : (vertex * vertex) sequence -> t -> t
+
   val to_seq : t -> (vertex * vertex) sequence
 end
 
@@ -700,6 +710,8 @@ module Map(O : Map.OrderedType) = struct
       else {m with edges=M.add v1 set m.edges}
     with Not_found -> m
 
+  let add v m = { m with vertices=S.add v m.vertices }
+
   let remove v m =
     { edges=M.remove v m.edges; vertices=S.remove v m.vertices }
 
@@ -718,14 +730,18 @@ module Map(O : Map.OrderedType) = struct
 
   let vertices_l m = S.fold (fun v acc -> v::acc) m.vertices []
 
-  let of_list l = List.fold_left (fun m (v1,v2) -> add_edge v1 v2 m) empty l
+  let add_list l m = List.fold_left (fun m (v1,v2) -> add_edge v1 v2 m) m l
+
+  let of_list l = add_list l empty
 
   let to_list m =
     M.fold
       (fun v set acc -> S.fold (fun v' acc -> (v,v')::acc) set acc)
       m.edges []
 
-  let of_seq seq = Seq.fold (fun m (v1,v2) -> add_edge v1 v2 m) empty seq
+  let add_seq seq m = Seq.fold (fun m (v1,v2) -> add_edge v1 v2 m) m seq
+
+  let of_seq seq = add_seq seq empty
 
   let to_seq m k = M.iter (fun v set -> S.iter (fun v' -> k(v,v')) set) m.edges
 end
diff --git a/src/data/CCGraph.mli b/src/data/CCGraph.mli
index b3f882f8..a7adf6ba 100644
--- a/src/data/CCGraph.mli
+++ b/src/data/CCGraph.mli
@@ -37,6 +37,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     This abstract notion of graph makes it possible to run the algorithms
     on any user-specific type that happens to have a graph structure.
 
+    Many graph algorithms here take a sequence of vertices as input.
+    If the user only has a single vertex (e.g., for a topological sort
+    from a given vertex), she can use [Seq.return x] to build a sequence
+    of one element.
+
     @since NEXT_RELEASE *)
 
 type 'a sequence = ('a -> unit) -> unit
@@ -337,7 +342,12 @@ val mk_mut_tbl : ?eq:('v -> 'v -> bool) ->
                 ('v, ('v * 'a * 'v)) mut_graph
 (** make a new mutable graph from a Hashtbl. Edges are labelled with type ['a] *)
 
-(** {2 Immutable Graph} *)
+(** {2 Immutable Graph}
+
+    A classic implementation of a graph structure on totally ordered vertices,
+    with unlabelled edges. The graph allows to add and remove edges and vertices,
+    and to iterate on edges and vertices.
+*)
 
 module type MAP = sig
   type vertex
@@ -352,7 +362,13 @@ module type MAP = sig
 
   val remove_edge : vertex -> vertex -> t -> t
 
+  val add : vertex -> t -> t
+  (** Add a vertex, possibly with no outgoing edge *)
+
   val remove : vertex -> t -> t
+  (** Remove the vertex and all its outgoing edges.
+      Edges that point to the vertex are {b NOT} removed, they must be
+      manually removed with {!remove_edge} *)
 
   val union : t -> t -> t
 
@@ -362,10 +378,14 @@ module type MAP = sig
 
   val of_list : (vertex * vertex) list -> t
 
+  val add_list : (vertex * vertex) list -> t -> t
+
   val to_list : t -> (vertex * vertex) list
 
   val of_seq : (vertex * vertex) sequence -> t
 
+  val add_seq : (vertex * vertex) sequence -> t -> t
+
   val to_seq : t -> (vertex * vertex) sequence
 end