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>

7 files changed, 104 insertions, 7 deletions

diff --git a/common/xfconf-errors.c b/common/xfconf-errors.c
index a565018..8f261e6 100644
--- a/common/xfconf-errors.c
+++ b/common/xfconf-errors.c
@@ -27,6 +27,15 @@
 #include "xfconf/xfconf-errors.h"
 #include "xfconf-alias.h"
 
+/**
+ * SECTION:xfconf-errors
+ * @title: Error Reporting
+ * @short_description: Xfconf library and daemon error descriptions
+ *
+ * Both the Xfconf daemon and library provide error information via the use of #GError
+ **/
+
+
 static const GDBusErrorEntry xfconf_daemon_dbus_error_entries[] = 
 {
     { XFCONF_ERROR_UNKNOWN, "org.xfce.Xfconf.Error.Unknown" },
@@ -56,13 +65,6 @@ static const GDBusErrorEntry xfconf_daemon_dbus_error_entries[] =
  **/
 
 
-/**
- * XfconfError:
- *
- * An enumeration listing the different kinds of errors under the
- * XFCONF_ERROR domain.
- **/
-
 GQuark
 xfconf_get_error_quark(void)
 {
@@ -79,6 +81,8 @@ xfconf_get_error_quark(void)
 /* unfortunately glib-mkenums can't generate types that are compatible with
  * dbus error names -- the 'nick' value is used, which can have dashes in it,
  * which dbus doesn't like. */
+
+
 GType
 xfconf_error_get_type(void)
 {
diff --git a/common/xfconf-types.c b/common/xfconf-types.c
index 24d115d..9a3fb4d 100644
--- a/common/xfconf-types.c
+++ b/common/xfconf-types.c
@@ -31,6 +31,14 @@
 
 #include <gobject/gvaluecollector.h>
 
+/**
+ * SECTION:xfconf-types
+ * @title: Xfconf Types
+ * @short_description: GObject types used by the Xfconf daemon and library
+ *
+ *  libgobject lacks GObject fundamental types for 16-bit signed and unsigned integers, which may be useful to use in an Xfconf store. GObject types for these primitive types are provided here.
+ **/
+
 
 /**
  * XFCONF_TYPE_UINT16:
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.
  *
diff --git a/xfconfd/xfconf-backend.c b/xfconfd/xfconf-backend.c
index fce42ac..f85836e 100644
--- a/xfconfd/xfconf-backend.c
+++ b/xfconfd/xfconf-backend.c
@@ -32,7 +32,33 @@ static gboolean xfconf_channel_is_valid(const gchar *channel,
                                         GError **error);
 
 /**
+ * SECTION:xfconf-backend
+ * @title: XfconfBackend
+ * @short_description: Interface for configuration store backends
+ *
+ *  XfconfBackend is an abstract interface that allows the Xfconf Daemon
+ *  to  use different backends for storing configuration data.
+ *  These backends can be flat text or binary files, a database,
+ *  or just about anything one could think of to store data.
+ **/
+
+/**
  * XfconfBackendInterface:
+ * @parent: GObject interface parent.
+ * @initialize: See xfconf_backend_initialize().
+ * @set: See xfconf_backend_set().
+ * @get: See xfconf_backend_get().
+ * @get_all: See xfconf_backend_get_all().
+ * @exists: See xfconf_backend_exists().
+ * @reset: See xfconf_backend_reset().
+ * @list_channels: See xfconf_backend_list_channels().
+ * @is_property_locked: See xfconf_backend_is_property_locked().
+ * @flush: See xfconf_backend_flush().
+ * @register_property_changed_func: See xfconf_backend_register_property_changed_func().
+ * @_xb_reserved0: Reserved for future expansion.
+ * @_xb_reserved1: Reserved for future expansion.
+ * @_xb_reserved2: Reserved for future expansion.
+ * @_xb_reserved3: Reserved for future expansion.
  *
  * An interface for implementing pluggable configuration store backends
  * into the Xfconf Daemon.