ocaml: eventchn: add ocamldoc strings to the interface

Also add a reference to tools/libxc/xenctrl.h, which is where
the underlying C functions are defined.

Signed-off-by: David Scott <dave.scott@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>

1 files changed, 29 insertions, 0 deletions

diff --git a/tools/ocaml/libs/eventchn/xeneventchn.mli b/tools/ocaml/libs/eventchn/xeneventchn.mli
index 74e581b4ee..a35743b340 100644
--- a/tools/ocaml/libs/eventchn/xeneventchn.mli
+++ b/tools/ocaml/libs/eventchn/xeneventchn.mli
@@ -14,22 +14,51 @@
  * GNU Lesser General Public License for more details.
  *)
 
+(** Event channel bindings: see tools/libxc/xenctrl.h *)
+
 exception Error of string
 
 type handle
+(** An initialised event channel interface. *)
 
 type t
+(** A local event channel. *)
 
 val to_int: t -> int
+
 val of_int: int -> t
 
 val init: unit -> handle
+(** Return an initialised event channel interface. On error it
+    will throw a Failure exception. *)
+
 val fd: handle -> Unix.file_descr
+(** Return a file descriptor suitable for Unix.select. When
+    the descriptor becomes readable, it is safe to call 'pending'.
+    On error it will throw a Failure exception. *)
 
 val notify : handle -> t -> unit
+(** Notify the given event channel. On error it will throw a
+    Failure exception. *)
+
 val bind_interdomain : handle -> int -> int -> t
+(** [bind_interdomain h domid remote_port] returns a local event
+    channel connected to domid:remote_port. On error it will
+    throw a Failure exception. *)
 
 val bind_dom_exc_virq : handle -> t
+(** Binds a local event channel to the VIRQ_DOM_EXC
+    (domain exception VIRQ). On error it will throw a Failure
+    exception. *)
+
 val unbind : handle -> t -> unit
+(** Unbinds the given event channel. On error it will throw a
+    Failure exception. *)
+
 val pending : handle -> t
+(** Returns the next event channel to become pending. On error it
+    will throw a Failure exception. *)
+
 val unmask : handle -> t -> unit
+(** Unmasks the given event channel. On error it will throw a
+    Failure exception. *)