[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [PATCH libvirt-glib] Add complete docs for the Libvirt GLib library



From: "Daniel P. Berrange" <berrange redhat com>

Flesh out the section intros for each of the Libvirt GLib
library modules, providing using examples where needed, and
adding any missing function docs.
---
 cfg.mk                                  |    2 +-
 configure.ac                            |    1 +
 docs/libvirt-glib/Libvirt-glib-docs.xml |    7 +--
 docs/libvirt-glib/Makefile.am           |    2 +
 docs/libvirt-glib/version.xml.in        |    1 +
 libvirt-glib/libvirt-glib-error.c       |   56 +++++++++++++++++++----
 libvirt-glib/libvirt-glib-event.c       |   65 ++++++++++++++++++++++++++
 libvirt-glib/libvirt-glib-main.c        |   76 +++++++++++++++++++++++++++++++
 8 files changed, 198 insertions(+), 12 deletions(-)
 create mode 100644 docs/libvirt-glib/version.xml.in

diff --git a/cfg.mk b/cfg.mk
index ed46aee..099ffa3 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -124,7 +124,7 @@ sc_check_author_list:
 	test $$fail = 0
 
 
-exclude_file_name_regexp--sc_bindtextdomain = ^(libvirt-gconfig/tests|examples)/
+exclude_file_name_regexp--sc_bindtextdomain = ^(libvirt-gconfig/tests|examples)/|libvirt-glib/libvirt-glib-event.c|libvirt-glib/libvirt-glib-main.c
 
 exclude_file_name_regexp--sc_preprocessor_indentation = ^*/*.[ch]
 
diff --git a/configure.ac b/configure.ac
index 31f82c9..4b974d4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -259,6 +259,7 @@ AC_OUTPUT(Makefile
           vapi/Makefile
           docs/Makefile
           docs/libvirt-glib/Makefile
+          docs/libvirt-glib/version.xml
           docs/libvirt-gobject/Makefile
           docs/libvirt-gconfig/Makefile
           libvirt-glib-1.0.pc
diff --git a/docs/libvirt-glib/Libvirt-glib-docs.xml b/docs/libvirt-glib/Libvirt-glib-docs.xml
index 5b6a873..f2f3572 100644
--- a/docs/libvirt-glib/Libvirt-glib-docs.xml
+++ b/docs/libvirt-glib/Libvirt-glib-docs.xml
@@ -3,21 +3,22 @@
                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
 [
   <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
   <bookinfo>
-    <title>Libvirt-glib Reference Manual</title>
+    <title>Libvirt GLib Reference Manual</title>
   </bookinfo>
 
   <chapter>
-    <title>Libvirt-glib</title>
+    <title>API Reference</title>
     <xi:include href="xml/libvirt-glib-main.xml"/>
     <xi:include href="xml/libvirt-glib-error.xml"/>
     <xi:include href="xml/libvirt-glib-event.xml"/>
   </chapter>
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
-     <xi:include href="xml/tree_index.sgml"/>
+    <xi:include href="xml/tree_index.sgml"/>
   </chapter>
   <index id="api-index-full">
     <title>API Index</title>
diff --git a/docs/libvirt-glib/Makefile.am b/docs/libvirt-glib/Makefile.am
index e45f4e2..186f8ff 100644
--- a/docs/libvirt-glib/Makefile.am
+++ b/docs/libvirt-glib/Makefile.am
@@ -39,3 +39,5 @@ GTKDOC_LIBS = \
 	$(top_builddir)/libvirt-glib/libvirt-glib-1.0.la
 
 include $(top_srcdir)/gtk-doc.make
+
+EXTRA_DIST += version.xml.in
diff --git a/docs/libvirt-glib/version.xml.in b/docs/libvirt-glib/version.xml.in
new file mode 100644
index 0000000..d78bda9
--- /dev/null
+++ b/docs/libvirt-glib/version.xml.in
@@ -0,0 +1 @@
+ VERSION@
diff --git a/libvirt-glib/libvirt-glib-error.c b/libvirt-glib/libvirt-glib-error.c
index 4a44216..7356aed 100644
--- a/libvirt-glib/libvirt-glib-error.c
+++ b/libvirt-glib/libvirt-glib-error.c
@@ -29,11 +29,51 @@
 #include "libvirt-glib/libvirt-glib.h"
 
 /**
- * gvir_error_new: (skip)
+ * SECTION:libvirt-glib-error
+ * @short_description: Convert libvirt error reports to GLib error reports
+ * @title: Error reporting
+ * @stability: Stable
+ * @include: libvirt-glib/libvirt-glib.h
+ *
+ * The libvirt API uses the <code>virError</code> structure for reporting
+ * errors back to the application programmer. The libvirt API errors are
+ * provided in thread-local variables, while the GLib standard practice is
+ * to return errors via out parameters. This library provides a simple way
+ * to fill in <code>GError **</code> output parameters with the contents
+ * of the most recent libvirt error object in the current thread.
+ *
+ * The <code>gvir_error_new</code>, <code>gvir_error_new_literal</code> and
+ * <code>gvir_error_new_valist</code> methods all return a newly created
+ * <code>GError *</code> object instance, differing only in the way the
+ * message needs to be provided. For most usage though, it is preferrable
+ * to use the <code>gvir_set_error</code>, <code>gvir_set_error_literal</code>
+ * and <code>gvir_set_error_valist</code> methods. These all accept a
+ * <code>GError **</code> argument and take care to only fill it if it
+ * points to a non-NULL location.
+ *
+ * <example>
+ * <title>Reporting GLib errors with libvirt APIs</title>
+ * <programlisting><![CDATA[
+ * gboolean myapp_start_guest(const gchar *xml, GError **error)
+ * {
+ *     if (virDomainCreate(conn, xml, 0) &lt; 0) {
+ *         gvir_set_error_literal(error, "Unable to start virtual machine");
+ *        return FALSE;
+ *     }
+ *
+ *     return TRUE;
+ * }
+ * ]]></programlisting>
+ * </example>
+ *
+ */
+
+/**
+ * gvir_error_new:
  * @domain: error domain
  * @code: error code
  * @format: printf()-style format for error message
- * @Varargs: parameters for message format
+ * @...: parameters for message format
  *
  * Creates a new #GError with the given @domain and @code,
  * and a message formatted with @format.
@@ -61,7 +101,7 @@ GError *gvir_error_new(GQuark domain,
 }
 
 /**
- * gvir_error_new_literal: (skip)
+ * gvir_error_new_literal:
  * @domain: error domain
  * @code: error code
  * @message: error message
@@ -99,7 +139,7 @@ GError *gvir_error_new_literal(GQuark domain,
 }
 
 /**
- * gvir_error_new_valist: (skip)
+ * gvir_error_new_valist:
  * @domain: error domain
  * @code: error code
  * @format: printf()-style format for error message
@@ -129,12 +169,12 @@ GError *gvir_error_new_valist(GQuark domain,
 
 
 /**
- * gvir_set_error: (skip)
+ * gvir_set_error:
  * @error: pointer to error location
  * @domain: error domain
  * @code: error code
  * @format: printf()-style format for error message
- * @Varargs: parameters for message format
+ * @...: parameters for message format
  *
  * If @error is NULL this does nothing. Otherwise it
  * creates a new #GError with the given @domain and @code,
@@ -164,7 +204,7 @@ void gvir_set_error(GError **error,
 
 
 /**
- * gvir_set_error_literal: (skip)
+ * gvir_set_error_literal:
  * @error: pointer to error location
  * @domain: error domain
  * @code: error code
@@ -190,7 +230,7 @@ void gvir_set_error_literal(GError **error,
 
 
 /**
- * gvir_set_error_valist: (skip)
+ * gvir_set_error_valist:
  * @error: pointer to error location
  * @domain: error domain
  * @code: error code
diff --git a/libvirt-glib/libvirt-glib-event.c b/libvirt-glib/libvirt-glib-event.c
index 6d54b10..94f4de8 100644
--- a/libvirt-glib/libvirt-glib-event.c
+++ b/libvirt-glib/libvirt-glib-event.c
@@ -31,6 +31,53 @@
 
 #include "libvirt-glib/libvirt-glib.h"
 
+/**
+ * SECTION:libvirt-glib-event
+ * @short_description: Integrate libvirt with the GMain event framework
+ * @title: Event loop
+ * @stability: Stable
+ * @include: libvirt-glib/libvirt-glib.h
+ *
+ * The libvirt API has the ability to provide applications with asynchronous
+ * notifications of interesting events. To enable this functionality though,
+ * applications must provide libvirt with an event loop implementation. The
+ * libvirt-glib API provides such an implementation, which naturally integrates
+ * with the GMain event loop framework.
+ *
+ * To enable use of the GMain event loop glue, the <code>gvir_event_register()</code>
+ * should be invoked. Once this is done, it is mandatory to have the default
+ * GMain event loop run by a thread in the application, usually the primary
+ * thread, eg by using <code>gtk_main()</code> or <code>g_application_run()</code>
+ *
+ * <example>
+ * <title>Registering for events with a GTK application</title>
+ * <programlisting><![CDATA[
+ * int main(int argc, char **argv) {
+ *   ...setup...
+ *   gvir_event_register();
+ *   ...more setup...
+ *   gtk_main();
+ *   return 0;
+ * }
+ * ]]></programlisting>
+ * </example>
+ *
+ * <example>
+ * <title>Registering for events using Appplication</title>
+ * <programlisting><![CDATA[
+ * int main(int argc, char **argv) {
+ *   ...setup...
+ *   GApplication *app = ...create some impl of GApplication...
+ *   gvir_event_register();
+ *   ...more setup...
+ *   g_application_run(app);
+ *   return 0;
+ * }
+ * ]]></programlisting>
+ * </example>
+ */
+
+
 #if GLIB_CHECK_VERSION(2, 31, 0)
 #define g_mutex_new() g_new0(GMutex, 1)
 #endif
@@ -414,6 +461,24 @@ static gpointer event_register_once(gpointer data G_GNUC_UNUSED)
     return NULL;
 }
 
+
+/**
+ * gvir_event_register:
+ *
+ * Registers a libvirt event loop implementation that is backed
+ * by the default <code>GMain</code> context. If invoked more
+ * than once this method will be a no-op. Applications should,
+ * however, take care not to register any another non-GLib
+ * event loop with libvirt.
+ *
+ * After invoking this method, it is mandatory to run the
+ * default GMain event loop. Typically this can be satisfied
+ * by invoking <code>gtk_main</code> or <code>g_application_run</code>
+ * in the application's main thread. Failure to run the event
+ * loop will mean no libvirt events get dispatched, and the
+ * libvirt keepalive timer will kill off libvirt connections
+ * frequently.
+ */
 void gvir_event_register(void)
 {
     static GOnce once = G_ONCE_INIT;
diff --git a/libvirt-glib/libvirt-glib-main.c b/libvirt-glib/libvirt-glib-main.c
index 0cb2dd5..3389de9 100644
--- a/libvirt-glib/libvirt-glib-main.c
+++ b/libvirt-glib/libvirt-glib-main.c
@@ -29,6 +29,36 @@
 
 #include "libvirt-glib-main.h"
 
+/**
+ * SECTION:libvirt-glib-main
+ * @short_description: Initialize the library
+ * @title: Library initialization
+ * @stability: Stable
+ * @include: libvirt-glib/libvirt-glib.h
+ *
+ * The Libvirt GLib library provides glue to integrate core libvirt
+ * infrastructure with the GLib library. This enables consistent
+ * error reporting procedures and a common event loop implementation
+ * for applications.
+ *
+ * Before using any functions in the Libvirt GLib library, it must be initialized
+ * by calling <code>gvir_init</code> or <code>gvir_init_check</code>.
+ *
+ * <example>
+ * <title>Initializing the Libvirt GLib library</title>
+ * <programlisting><![CDATA[
+ * int main(int argc, char **argv) {
+ *   ...setup...
+ *   gvir_init(&argc, &argv);
+ *   ...more setup...
+ *   gtk_main();
+ *   return 0;
+ * }
+ * ]]></programlisting>
+ * </example>
+ *
+ */
+
 static void
 gvir_error_func(gpointer opaque G_GNUC_UNUSED,
                 virErrorPtr err)
@@ -37,6 +67,33 @@ gvir_error_func(gpointer opaque G_GNUC_UNUSED,
 }
 
 
+
+/**
+ * gvir_init:
+ * @argc: (inout): Address of the argc parameter of your main() function (or 0
+ *     if argv is NULL). This will be changed if any arguments were handled.
+ * @argv: (array length=argc) (inout) (allow-none): Address of the
+ *     <parameter>argv</parameter> parameter of main(), or %NULL. Any options
+ *     understood by GTK+ are stripped before return.
+ *
+ * Call this function before using any other Libvirt GLib functions in your applications.
+ * It will initialize everything needed to operate the toolkit and parses some standard
+ * command line options.
+ *
+ * Although you are expected to pass the @argc, @argv parameters from main() to this
+ * function, it is possible to pass NULL if @argv is not available or commandline
+ * handling is not required.
+ *
+ * @argc and @argv are adjusted accordingly so your own code will never see those
+ * standard arguments.
+ *
+ * This method will also turn on debug logging of the library if the
+ * <literal>LIBVIRT_GLIB_DEBUG</literal> environment variable is set.
+ *
+ * This function will terminate your program if it was unable to initialize
+ * for some reason. If you want the program to fall back to an alternate
+ * mode of operation call <code>gvir_init_check</code> instead.
+ */
 void gvir_init(int *argc,
                 char ***argv)
 {
@@ -58,6 +115,25 @@ static void gvir_log_handler(const gchar *log_domain G_GNUC_UNUSED,
 }
 
 
+/**
+ * gvir_init_check:
+ * @argc: (inout): Address of the argc parameter of your main() function (or 0
+ *     if argv is NULL). This will be changed if any arguments were handled.
+ * @argv: (array length=argc) (inout) (allow-none): Address of the
+ *     <parameter>argv</parameter> parameter of main(), or %NULL. Any options
+ *     understood by GTK+ are stripped before return.
+ * @err: filled with the error information if initialized failed.
+ *
+ * This function does the same work as gvir_init() with only a single
+ * change: It does not terminate the program if the Libvirt GLib library
+ * can't be initialized. Instead it returns %FALSE on failure.
+ *
+ * This way the application can fall back to some other mode of
+ * operation.
+ *
+ * Return value: %TRUE if the library was successfully initialized,
+ *     %FALSE otherwise
+ */
 gboolean gvir_init_check(int *argc G_GNUC_UNUSED,
                          char ***argv G_GNUC_UNUSED,
                          GError **err G_GNUC_UNUSED)
-- 
1.7.10


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]