[Xfce4-commits] <xfce4-panel:devel> Add API docs for version information.

[Nick Schermer]

Updating branch refs/heads/devel
         to 9b12b811e73601f034bb08df02339a212be63e8f (commit)
       from 9f5a9a47649674230c218b29eb553041b94e24bc (commit)

commit 9b12b811e73601f034bb08df02339a212be63e8f
Author: Nick Schermer <nick at xfce.org>
Date:   Fri Nov 27 13:43:52 2009 +0100

    Add API docs for version information.

 libxfce4panel/libxfce4panel-config.c    |   57 ++++++++++++++++++++++++++-----
 libxfce4panel/libxfce4panel-config.h.in |   36 +++++++++++++++++++
 2 files changed, 84 insertions(+), 9 deletions(-)

diff --git a/libxfce4panel/libxfce4panel-config.c b/libxfce4panel/libxfce4panel-config.c
index ad6af1d..4948626 100644
--- a/libxfce4panel/libxfce4panel-config.c
+++ b/libxfce4panel/libxfce4panel-config.c
@@ -25,8 +25,47 @@
 
 
 
+/**
+ * libxfce4panel_major_version:
+ *
+ * The major version number of the libxfce4panel library (e.g. in
+ * version 4.8.0 this is 4).
+ *
+ * This variable is in the library, so represents the
+ * libxfce4panel library you have linked against. Contrast with the
+ * #LIBXFCE4PANEL_MAJOR_VERSION macro, which represents the major
+ * version of the libxfce4panel headers you have included.
+ **/
 const guint libxfce4panel_major_version = LIBXFCE4PANEL_MAJOR_VERSION;
+
+
+
+/**
+ * libxfce4panel_minor_version:
+ *
+ * The minor version number of the libxfce4panel library (e.g. in
+ * version 4.8.0 this is 8).
+ *
+ * This variable is in the library, so represents the
+ * libxfce4panel library you have linked against. Contrast with the
+ * #LIBXFCE4PANEL_MINOR_VERSION macro, which represents the minor
+ * version of the libxfce4panel headers you have included.
+ **/
 const guint libxfce4panel_minor_version = LIBXFCE4PANEL_MINOR_VERSION;
+
+
+
+/**
+ * libxfce4panel_micro_version:
+ *
+ * The micro version number of the libxfce4panel library (e.g. in
+ * version 4.8.0 this is 0).
+ *
+ * This variable is in the library, so represents the
+ * libxfce4panel library you have linked against. Contrast with the
+ * #LIBXFCE4PANEL_MICRO_VERSION macro, which represents the micro
+ * version of the libxfce4panel headers you have included.
+ **/
 const guint libxfce4panel_micro_version = LIBXFCE4PANEL_MICRO_VERSION;
 
 
@@ -37,16 +76,16 @@ const guint libxfce4panel_micro_version = LIBXFCE4PANEL_MICRO_VERSION;
  * @required_minor: the required minor version.
  * @required_micro: the required micro version.
  *
- * Checks that the <systemitem class="library">libxfce4panel</systemitem> library
- * in use is compatible with the given version. Generally you would pass in
- * the constants #LIBXFCE4PANEL_MAJOR_VERSION, #LIBXFCE4PANEL_MINOR_VERSION and
- * #LIBXFCE4PANEL_MICRO_VERSION as the three arguments to this function; that produces
- * a check that the library in use is compatible with the version of
- * <systemitem class="library">libxfce4panel</systemitem> the extension was
+ * Checks that the libxfce4panel library in use is compatible with
+ * the given version. Generally you would pass in the constants
+ * #LIBXFCE4PANEL_MAJOR_VERSION, #LIBXFCE4PANEL_MINOR_VERSION and
+ * #LIBXFCE4PANEL_MICRO_VERSION as the three arguments to this
+ * function; that produces a check that the library in use is
+ * compatible with the version of libxfce4panel the extension was
  * compiled against.
  *
  * <example>
- * <title>Checking the runtime version of the Libxfce4ui library</title>
+ * <title>Checking the runtime version of the Libxfce4panel library</title>
  * <programlisting>
  * const gchar *mismatch;
  * mismatch = libxfce4panel_check_version (LIBXFCE4PANEL_MAJOR_VERSION,
@@ -64,8 +103,8 @@ const guint libxfce4panel_micro_version = LIBXFCE4PANEL_MICRO_VERSION;
  **/
 const gchar *
 libxfce4panel_check_version (guint required_major,
-                          guint required_minor,
-                          guint required_micro)
+                             guint required_minor,
+                             guint required_micro)
 {
   if (required_major > LIBXFCE4PANEL_MAJOR_VERSION)
     return "Xfce Panel version too old (major mismatch)";
diff --git a/libxfce4panel/libxfce4panel-config.h.in b/libxfce4panel/libxfce4panel-config.h.in
index 3970d9b..096d6e7 100644
--- a/libxfce4panel/libxfce4panel-config.h.in
+++ b/libxfce4panel/libxfce4panel-config.h.in
@@ -27,10 +27,46 @@
 
 G_BEGIN_DECLS
 
+/**
+ * LIBXFCE4PANEL_MAJOR_VERSION:
+ * 
+ * The major version number of the libxfce4panel library.
+ * Like libxfce4panel_major_version, but from the headers used at 
+ * application compile time, rather than from the library 
+ * linked against at application run time.
+ **/
 #define LIBXFCE4PANEL_MAJOR_VERSION (@LIBXFCE4PANEL_VERSION_MAJOR@)
+
+/**
+ * LIBXFCE4PANEL_MINOR_VERSION:
+ * 
+ * The minor version number of the libxfce4panel library.
+ * Like libxfce4panel_minor_version, but from the headers used at 
+ * application compile time, rather than from the library 
+ * linked against at application run time.
+ **/
 #define LIBXFCE4PANEL_MINOR_VERSION (@LIBXFCE4PANEL_VERSION_MINOR@)
+
+/**
+ * LIBXFCE4PANEL_MICRO_VERSION:
+ * 
+ * The micro version number of the libxfce4panel library.
+ * Like libxfce4panel_micro_version, but from the headers used at 
+ * application compile time, rather than from the library 
+ * linked against at application run time
+ **/
 #define LIBXFCE4PANEL_MICRO_VERSION (@LIBXFCE4PANEL_VERSION_MICRO@)
 
+/**
+ * LIBXFCE4PANEL_CHECK_VERSION:
+ * @major : the major version number.
+ * @minor : the minor version number.
+ * @micro : the micro version number.
+ * 
+ * Checks the version of the libxfce4panel library. Returns
+ * %TRUE if the version of the libxfce4panel header files is
+ * the same as or newer than the passed-in version.
+ **/
 #define LIBXFCE4PANEL_CHECK_VERSION(major,minor,micro) \
   (LIBXFCE4PANEL_MAJOR_VERSION > (major) \
    || (LIBXFCE4PANEL_MAJOR_VERSION == (major) \