From: Richard W.M. Jones <rjones@redhat.com> <"Richard W.M. Jones <rjones@redhat.com>">
Date: Sat, 19 Jan 2008 14:27:01 +0000 (+0000)
Subject: Documentation updates.
X-Git-Tag: 1.0.4~59
X-Git-Url: http://git.annexia.org/?p=virt-top.git;a=commitdiff_plain;h=3a52f5d4f1becb1fc31eecf4a3a93542f2ff89b8

Documentation updates.
---

diff --git a/libvirt/README b/libvirt/README
index c94cccb..be8300d 100644
--- a/libvirt/README
+++ b/libvirt/README
@@ -1,11 +1,29 @@
-README for generated code
--------------------------
+README
+======
+
+The public interface is described in 'libvirt.mli'.  You may prefer to
+do 'make doc' at the top level source directory and then read the HTML
+documentation starting at html/index.html.
+
+'libvirt.ml' describes how OCaml functions map to C functions.
+
+'libvirt_c*.c' are the C functions which map OCaml objects to C
+objects and vice versa (see next section).
+
+Generated code
+--------------
 
 The C bindings in 'libvirt_c.c' are now generated automatically by a
 Perl script called 'generator.pl'.  You do not normally need to run
 this script, but you may need to if you want to extend libvirt
 coverage.
 
+The majority of the functions are now generated automatically, but
+there are a few one-off bindings (eg. one-of-a-type functions,
+functions with particularly complex mappings).  Our eventual aim to is
+autogenerate as much as possible.  Use 'make autostatus' in this
+directory to find out how we're doing.
+
 The generated 'libvirt_c.c' #includes some other C files in this
 directory:
 
@@ -25,3 +43,7 @@ directory:
 
     An epilogue which defines some standard static functions (eg.) for
     wrapping and unwrapping libvirt objects.
+
+The key to understanding the generator is to look at the generated
+code (libvirt_c.c) first, and go from there back to parts of the
+generator script.
diff --git a/libvirt/generator.pl b/libvirt/generator.pl
index 4fd07b8..40005c0 100755
--- a/libvirt/generator.pl
+++ b/libvirt/generator.pl
@@ -629,6 +629,13 @@ END
 
 printf "$0: warning: %d unimplemented functions\n", scalar (@unimplemented);
 
+print F <<'END';
+/* The following functions are unimplemented and always fail.
+ * See generator.pl '@unimplemented'
+ */
+
+END
+
 foreach my $c_external_name (@unimplemented) {
     print F <<END
 CAMLprim value
diff --git a/libvirt/libvirt_c.c b/libvirt/libvirt_c.c
index dc7b3c9..8c31710 100644
--- a/libvirt/libvirt_c.c
+++ b/libvirt/libvirt_c.c
@@ -1485,6 +1485,10 @@ ocaml_libvirt_storage_vol_get_name (value volv)
 #endif
 }
 
+/* The following functions are unimplemented and always fail.
+ * See generator.pl '@unimplemented'
+ */
+
 CAMLprim value
 ocaml_libvirt_domain_create_job ()
 {