From: Richard W.M. Jones <rjones@redhat.com>
Date: Sun, 17 Jul 2011 09:29:47 +0000 (+0100)
Subject: ocaml: Generate ocamldoc.
X-Git-Tag: 1.11.19~9
X-Git-Url: http://git.annexia.org/?a=commitdiff_plain;h=cd00157efca760ce043dcae216d921841dd25ff9;p=libguestfs.git

ocaml: Generate ocamldoc.

Also includes improvements to the OCaml documentation.
---

diff --git a/configure.ac b/configure.ac
index 3d2a3e2..435b5e1 100644
--- a/configure.ac
+++ b/configure.ac
@@ -484,6 +484,8 @@ AM_CONDITIONAL([HAVE_OCAML],
                [test "x$OCAMLC" != "xno" && test "x$OCAMLFIND" != "xno"])
 AM_CONDITIONAL([HAVE_OCAML_PCRE],
                [test "x$OCAMLC" != "xno" && test "x$OCAMLFIND" != "xno" && test "x$OCAML_PKG_pcre" != "xno"])
+AM_CONDITIONAL([HAVE_OCAMLDOC],
+               [test "x$OCAMLDOC" != "xno"])
 
 dnl Check for Perl (optional, for Perl bindings).
 PERL=no
diff --git a/generator/generator_ocaml.ml b/generator/generator_ocaml.ml
index 594ed4e..51bc3d6 100644
--- a/generator/generator_ocaml.ml
+++ b/generator/generator_ocaml.ml
@@ -35,9 +35,21 @@ let rec generate_ocaml_mli () =
   generate_header OCamlStyle LGPLv2plus;
 
   pr "\
-(** For API documentation you should refer to the C API
-    in the guestfs(3) manual page.  The OCaml API uses almost
-    exactly the same calls. *)
+(** libguestfs bindings for OCaml.
+
+    For API documentation, the canonical reference is the
+    {{:http://libguestfs.org/guestfs.3.html}guestfs(3)} man page.
+    The OCaml API uses almost exactly the same calls.
+
+    For examples written in OCaml see the
+    {{:http://libguestfs.org/guestfs-ocaml.3.html}guestfs-ocaml(3)} man page.
+    *)
+
+(** {2 Module style API}
+
+    This is the module-style API.  There is also an object-oriented API
+    (see the end of this file and {!guestfs})
+    which is functionally completely equivalent, but is more compact. *)
 
 type t
 (** A [guestfs_h] handle. *)
@@ -46,15 +58,15 @@ exception Error of string
 (** This exception is raised when there is an error. *)
 
 exception Handle_closed of string
-(** This exception is raised if you use a {!Guestfs.t} handle
+(** This exception is raised if you use a {!t} handle
     after calling {!close} on it.  The string is the name of
     the function. *)
 
 val create : unit -> t
-(** Create a {!Guestfs.t} handle. *)
+(** Create a {!t} handle. *)
 
 val close : t -> unit
-(** Close the {!Guestfs.t} handle and free up all resources used
+(** Close the {!t} handle and free up all resources used
     by it immediately.
 
     Handles are closed by the garbage collector when they become
@@ -112,9 +124,24 @@ val user_cancel : t -> unit
 
   (* The actions. *)
   List.iter (
-    fun (name, style, _, _, _, shortdesc, _) ->
+    fun (name, style, _, flags, _, shortdesc, _) ->
+      let deprecated =
+        try Some (find_map (function DeprecatedBy fn -> Some fn | _ -> None)
+                    flags)
+        with Not_found -> None in
+      let in_docs = not (List.mem NotInDocs flags) in
+
       generate_ocaml_prototype name style;
-      pr "(** %s *)\n" shortdesc;
+
+      if in_docs then (
+        pr "(** %s" shortdesc;
+        (match deprecated with
+         | None -> ()
+         | Some replacement ->
+             pr "\n\n    @deprecated Use {!%s} instead\n" replacement
+        );
+        pr " *)\n";
+      );
       pr "\n"
   ) all_functions_sorted;
 
@@ -122,20 +149,23 @@ val user_cancel : t -> unit
 (** {2 Object-oriented API}
 
     This is an alternate way of calling the API using an object-oriented
-    style, so you can use [g#add_drive_opts filename] instead of
-    [Guestfs.add_drive_opts g filename].  Apart from the different style,
-    it offers exactly the same functionality.
+    style, so you can use
+    [g#]{{!guestfs.add_drive_opts}add_drive_opts} [filename]
+    instead of [Guestfs.add_drive_opts g filename].
+    Apart from the different style, it offers exactly the same functionality.
 
     Calling [new guestfs ()] creates both the object and the handle.
     The object and handle are closed either implicitly when the
-    object is garbage collected, or explicitly by calling the [g#close ()]
-    method.
+    object is garbage collected, or explicitly by calling the
+    [g#]{{!guestfs.close}close} [()] method.
 
-    You can get the {!Guestfs.t} handle by calling [g#ocaml_handle].
+    You can get the {!t} handle by calling
+    [g#]{{!guestfs.ocaml_handle}ocaml_handle}.
 
     Note that methods that take no parameters (except the implicit handle)
     get an extra unit [()] parameter.  This is so you can create a
-    closure from the method easily.  For example [g#get_verbose ()]
+    closure from the method easily.  For example
+    [g#]{{!guestfs.get_verbose}get_verbose} [()]
     calls the method, whereas [g#get_verbose] is a function. *)
 
 class guestfs : unit -> object
diff --git a/ocaml/Makefile.am b/ocaml/Makefile.am
index c07b9c5..252a337 100644
--- a/ocaml/Makefile.am
+++ b/ocaml/Makefile.am
@@ -25,8 +25,10 @@ generator_built = \
 
 EXTRA_DIST = \
 	$(generator_built) \
+	.depend \
 	guestfs_c.c guestfs_c.h \
-	.depend META.in \
+	html/.gitignore \
+	META.in \
 	run-bindtests \
 	t/*.ml
 
@@ -56,6 +58,15 @@ guestfs_c.o: guestfs_c.c
 guestfs_c_actions.o: guestfs_c_actions.c
 	$(CC) $(AM_CPPFLAGS) $(CFLAGS) -fPIC -Wall -c $<
 
+if HAVE_OCAMLDOC
+
+noinst_DATA += html/index.html
+
+html/index.html: guestfs*.mli guestfs*.ml
+	mkdir -p html
+	-$(OCAMLDOC) -d html -html $^
+endif
+
 TESTS_ENVIRONMENT = \
 	LD_LIBRARY_PATH=$(top_builddir)/src/.libs \
 	LIBGUESTFS_PATH=$(top_builddir)/appliance \
diff --git a/ocaml/html/.gitignore b/ocaml/html/.gitignore
new file mode 100644
index 0000000..e9f06bd
--- /dev/null
+++ b/ocaml/html/.gitignore
@@ -0,0 +1,2 @@
+style.css
+*.html