Update documentation api

- Re-add correct sections / headers to generate a nice documentation
- More modern way to handle documentation with gtk-doc (no more sgml
templates).

Signed-off-by: Ali Abdallah <ali@xfce.org>

4 files changed, 59 insertions, 0 deletions

diff --git a/xfconf/xfconf-binding.c b/xfconf/xfconf-binding.c
index a5df2c7..22db0f4 100644
--- a/xfconf/xfconf-binding.c
+++ b/xfconf/xfconf-binding.c
@@ -33,6 +33,22 @@
 #include "common/xfconf-common-private.h"
 
 
+/**
+ * SECTION:xfconf-binding
+ * @title: Xfconf-GObject Binding
+ * @short_description: Functions to bind Xfconf properties to GObject properties
+ *
+ * Often it may be useful to bind an Xfconf property to a GObject property.
+ * Settings dialogs often display the current value of an Xfconf property,
+ * and a user may edit the value to change the value in the Xfconf store.
+ * If the Xfconf property changes outside the settings dialog, the user will
+ * usually want to see the settings dialog automatically update to reflect
+ * the new value.
+ *
+ * With a single line of code, Xfconf's binding functionality can automate
+ * all this.
+ **/
+
 typedef struct
 {
     XfconfChannel *channel;
@@ -516,6 +532,7 @@ xfconf_g_property_bind(XfconfChannel *channel,
  *
  * Returns: an ID number that can be used to later remove the
  *          binding.
+ *
  **/
 gulong
 xfconf_g_property_bind_gdkcolor(XfconfChannel *channel,
@@ -577,6 +594,8 @@ xfconf_g_property_bind_gdkcolor(XfconfChannel *channel,
  *
  * Returns: an ID number that can be used to later remove the
  *          binding.
+ *
+ * Since: 4.12.1
  **/
 gulong
 xfconf_g_property_bind_gdkrgba(XfconfChannel *channel,
diff --git a/xfconf/xfconf-channel.c b/xfconf/xfconf-channel.c
index 5741664..1dbdfdc 100644
--- a/xfconf/xfconf-channel.c
+++ b/xfconf/xfconf-channel.c
@@ -48,6 +48,17 @@
                                        : (gchar *)(property) )
 
 /**
+ * SECTION:xfconf-channel
+ * @title: XfconfChannel
+ * @short_description: An application-defined domain for storing configuration settings
+ *
+ * An XfconfChannel is a representation of a restricted domain or
+ * namespace that an application can define to store configuration
+ * settings.  This is to ensure that different applications do not store
+ * configuration keys with the same names.
+ **/
+
+/**
  * XfconfChannel:
  *
  * An opaque structure that holds state about a channel.
diff --git a/xfconf/xfconf-errors.h b/xfconf/xfconf-errors.h
index 4b489fd..b80af64 100644
--- a/xfconf/xfconf-errors.h
+++ b/xfconf/xfconf-errors.h
@@ -32,6 +32,22 @@
 
 G_BEGIN_DECLS
 
+/**
+ * XfconfError:
+ * @XFCONF_ERROR_UNKNOWN: An unknown error occurred
+ * @XFCONF_ERROR_CHANNEL_NOT_FOUND: The specified channel does not exist
+ * @XFCONF_ERROR_PROPERTY_NOT_FOUND: The specified property does not exist on the channel
+ * @XFCONF_ERROR_READ_FAILURE: There was a failure reading from the configuration store
+ * @XFCONF_ERROR_WRITE_FAILURE: There was a failure writing to the configuration store
+ * @XFCONF_ERROR_PERMISSION_DENIED: The user is not allowed to read or write to the channel or property
+ * @XFCONF_ERROR_INTERNAL_ERROR: An internal error (likely a bug in xfconf) occurred
+ * @XFCONF_ERROR_NO_BACKEND: No backends were found, or those found could not be loaded
+ * @XFCONF_ERROR_INVALID_PROPERTY: The property name specified was invalid
+ * @XFCONF_ERROR_INVALID_CHANNEL: The channel name specified was invalid
+ *
+ * An enumeration listing the different kinds of errors under the XFCONF_ERROR domain.
+ *
+ **/
 typedef enum
 {
     XFCONF_ERROR_UNKNOWN = 0,
diff --git a/xfconf/xfconf.c b/xfconf/xfconf.c
index c125571..c933582 100644
--- a/xfconf/xfconf.c
+++ b/xfconf/xfconf.c
@@ -83,6 +83,19 @@ _xfconf_named_struct_free(XfconfNamedStruct *ns)
 /* public api */
 
 /**
+ * SECTION:xfconf
+ * @title: Xfconf Library Core
+ * @short_description: Init routines and core functionality for libxfconf
+ *
+ * Before libxfconf can be used, it must be initialized by calling
+ * xfconf_init().  To free resources used by the library, call
+ * xfconf_shutdown().  These calls are "recursive": multiple calls to
+ * xfconf_init() are allowed, but each call must be matched by a
+ * separate call to xfconf_shutdown() to really free the library's
+ * resources.
+ **/
+
+/**
  * xfconf_init:
  * @error: An error return.
  *