From 295daf5d500bf1b6eebfe8b88a2901b4a3eafd4a Mon Sep 17 00:00:00 2001 From: Romain B Date: Fri, 23 Jun 2017 15:40:44 +0200 Subject: 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 --- common/xfconf-errors.c | 18 +++++++++++------- common/xfconf-types.c | 8 ++++++++ xfconf/xfconf-binding.c | 19 +++++++++++++++++++ xfconf/xfconf-channel.c | 11 +++++++++++ xfconf/xfconf-errors.h | 16 ++++++++++++++++ xfconf/xfconf.c | 13 +++++++++++++ xfconfd/xfconf-backend.c | 26 ++++++++++++++++++++++++++ 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 +/** + * 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 @@ -47,6 +47,17 @@ (property), NULL) \ : (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: * 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 @@ -82,6 +82,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 @@ -31,8 +31,34 @@ static gboolean xfconf_property_is_valid(const gchar *property, 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. -- cgit v1.2.1