From 27fada20be7feba6783abc5b6cad91ee274ad3df Mon Sep 17 00:00:00 2001 From: Richard Hughes Date: Mon, 25 Jan 2010 16:26:47 +0000 Subject: trivial: add some gtk-doc markup into libupower-glib and hook it up to the build system --- configure.ac | 18 +++-- devkit-power-gobject/dkp-version.h.in | 4 +- doc/.gitignore | 1 + doc/Makefile.am | 12 ++- doc/upower-docs.xml | 35 ++++++-- libupower-glib/Makefile.am | 6 -- libupower-glib/up-client.c | 147 +++++++++++++++++++++++++--------- libupower-glib/up-client.h | 2 +- libupower-glib/up-device.c | 127 +++++++++++++++++++++++------ libupower-glib/up-device.h | 10 +-- libupower-glib/up-types.c | 10 +++ libupower-glib/up-types.h | 20 +++++ libupower-glib/up-version.h.in | 42 ++++++++-- libupower-glib/upower.h | 10 +++ po/it.po | 4 +- 15 files changed, 342 insertions(+), 106 deletions(-) diff --git a/configure.ac b/configure.ac index a3b2431..8bd10f6 100644 --- a/configure.ac +++ b/configure.ac @@ -12,18 +12,22 @@ AC_CONFIG_SRCDIR(src) AM_INIT_AUTOMAKE([1.9 tar-ustar dist-bzip2]) AM_CONFIG_HEADER(config.h) AC_CONFIG_MACRO_DIR([m4]) -AM_MAINTAINER_MODE -AC_CONFIG_MACRO_DIR([m4]) GOBJECT_INTROSPECTION_CHECK([0.6.7]) # enable nice build output on automake1.11 m4_ifdef([AM_SILENT_RULES],[AM_SILENT_RULES([yes])]) -# use this in dkp-version.h +# use this in up-version.h +UP_MAJOR_VERSION=up_major_version +UP_MINOR_VERSION=up_minor_version +UP_MICRO_VERSION=up_micro_version AC_SUBST(VERSION) +AC_SUBST(UP_MAJOR_VERSION) +AC_SUBST(UP_MINOR_VERSION) +AC_SUBST(UP_MICRO_VERSION) -# libtool versioning - this applies to devkit-power-gobject +# libtool versioning - this applies to libupower-glib # # See http://sources.redhat.com/autobook/autobook/autobook_91.html#SEC91 for details # @@ -208,7 +212,7 @@ if test "x$GCC" = "xyes"; then fi IT_PROG_INTLTOOL([0.40.0]) -GETTEXT_PACKAGE=DeviceKit-power +GETTEXT_PACKAGE=UPower AC_SUBST([GETTEXT_PACKAGE]) AM_GLIB_GNU_GETTEXT AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE],["$GETTEXT_PACKAGE"],[gettext domain]) @@ -237,8 +241,8 @@ po/Makefile.in dnl ========================================================================== echo " - DeviceKit-power $VERSION - ======================= + UPower $VERSION + ========================= prefix: ${prefix} libdir: ${libdir} diff --git a/devkit-power-gobject/dkp-version.h.in b/devkit-power-gobject/dkp-version.h.in index 57daa58..8a1635c 100644 --- a/devkit-power-gobject/dkp-version.h.in +++ b/devkit-power-gobject/dkp-version.h.in @@ -32,8 +32,6 @@ /* check whether a the version is above the compile time version. */ -#define DKP_CHECK_VERSION(ver) \ - (DKP_COMPILE_VERSION > (ver) || \ - (DKP_COMPILE_VERSION == (ver))) +#define DKP_CHECK_VERSION(ver) (1) #endif /* __DKP_VERSION_H */ diff --git a/doc/.gitignore b/doc/.gitignore index e3be474..6d049dc 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -12,4 +12,5 @@ html tmpl version.xml xml +.libs diff --git a/doc/Makefile.am b/doc/Makefile.am index 479429b..be6ed02 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -6,7 +6,7 @@ NULL = AUTOMAKE_OPTIONS = 1.7 # The name of the module. -DOC_MODULE=upower +DOC_MODULE=UPower # The top-level SGML file. DOC_MAIN_SGML_FILE=upower-docs.xml @@ -25,6 +25,7 @@ CFILE_GLOB= # Headers to ignore IGNORE_HFILES= \ + config.h \ $(NULL) # CFLAGS and LDFLAGS for compiling scan program. Only needed @@ -32,11 +33,16 @@ IGNORE_HFILES= \ INCLUDES = \ $(DBUS_GLIB_CFLAGS) \ $(GLIB_CFLAGS) \ - -I$(top_srcdir)/policy \ - -I$(top_builddir)/policy \ + -I$(top_srcdir)/libupower-glib \ + -I$(top_builddir)/libupower-glib \ + $(NULL) + +UPOWER_GLIB_LIBS = \ + $(top_builddir)/libupower-glib/libupower-glib.la \ $(NULL) GTKDOC_LIBS = \ + $(UPOWER_GLIB_LIBS) \ $(DBUS_GLIB_LIBS) \ $(NULL) diff --git a/doc/upower-docs.xml b/doc/upower-docs.xml index 14438d1..9b01704 100644 --- a/doc/upower-docs.xml +++ b/doc/upower-docs.xml @@ -9,13 +9,13 @@ Version &version; - David - Zeuthen - -
- davidz@redhat.com -
- + Richard + Hughes + +
+ richard@hughsie.com +
+ @@ -69,6 +69,27 @@ + + libpackagekit GObjects + + + This part documents GObjects used in libupower-glib. + + + + + + + + libupower-glib helpers + + + This part documents helper funtions in libupower-glib. + + + + + Manual Pages diff --git a/libupower-glib/Makefile.am b/libupower-glib/Makefile.am index b4d116a..25ea580 100644 --- a/libupower-glib/Makefile.am +++ b/libupower-glib/Makefile.am @@ -47,12 +47,6 @@ libupower_glib_la_CFLAGS = \ EXTRA_DIST = \ up-client.h \ up-device.h \ - up-enum.h \ - up-history-item.h \ - up-qos-item.h \ - up-stats-item.h \ - up-wakeup-item.h \ - up-wakeups.h \ up-version.h.in CLEANFILES = $(BUILT_SOURCES) diff --git a/libupower-glib/up-client.c b/libupower-glib/up-client.c index 7e211ca..f858063 100644 --- a/libupower-glib/up-client.c +++ b/libupower-glib/up-client.c @@ -19,6 +19,16 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** + * SECTION:up-client + * @short_description: Main client object for accessing the UPower daemon + * + * A helper GObject to use for accessing UPower information, and to be notified + * when it is changed. + * + * See also: #UpDevice + */ + #include "config.h" #include @@ -35,7 +45,12 @@ static void up_client_finalize (GObject *object); #define UP_CLIENT_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), UP_TYPE_CLIENT, UpClientPrivate)) -struct UpClientPrivate +/** + * UpClientPrivate: + * + * Private #UpClient data + **/ +struct _UpClientPrivate { DBusGConnection *bus; DBusGProxy *proxy; @@ -76,9 +91,9 @@ static gpointer up_client_object = NULL; G_DEFINE_TYPE (UpClient, up_client, G_TYPE_OBJECT) -/** +/* * up_client_get_device: - **/ + */ static UpDevice * up_client_get_device (UpClient *client, const gchar *object_path) { @@ -111,9 +126,9 @@ up_client_get_devices (UpClient *client) return g_ptr_array_ref (client->priv->array); } -/** +/* * up_client_get_devices_private: - **/ + */ static GPtrArray * up_client_get_devices_private (UpClient *client, GError **error) { @@ -139,8 +154,8 @@ up_client_get_devices_private (UpClient *client, GError **error) /** * up_client_suspend_sync: - * @client : a #UpClient instance. - * @error : a #GError. + * @client: a #UpClient instance. + * @error: a #GError, or %NULL. * * Puts the computer into a low power state, but state is not preserved if the * power is lost. @@ -182,8 +197,8 @@ out: /** * up_client_hibernate_sync: - * @client : a #UpClient instance. - * @error : a #GError. + * @client: a #UpClient instance. + * @error: a #GError. * * Puts the computer into a low power state, where state is preserved if the * power is lost. @@ -223,6 +238,14 @@ out: /** * up_client_get_properties_sync: + * @client: a #UpClient instance. + * @error: a #GError, or %NULL. + * + * Get all the properties from UPower daemon. + * + * Return value: %TRUE for success, else %FALSE. + * + * Since: 0.9.0 **/ gboolean up_client_get_properties_sync (UpClient *client, GError **error) @@ -331,9 +354,9 @@ out: /** * up_client_get_daemon_version: - * @client : a #UpClient instance. + * @client: a #UpClient instance. * - * Get DeviceKit-power daemon version. + * Get UPower daemon version. * * Return value: string containing the daemon version, e.g. 008 * @@ -349,7 +372,7 @@ up_client_get_daemon_version (UpClient *client) /** * up_client_get_can_hibernate: - * @client : a #UpClient instance. + * @client: a #UpClient instance. * * Get whether the system is able to hibernate. * @@ -367,7 +390,7 @@ up_client_get_can_hibernate (UpClient *client) /** * up_client_get_lid_is_closed: - * @client : a #UpClient instance. + * @client: a #UpClient instance. * * Get whether the laptop lid is closed. * @@ -383,7 +406,7 @@ up_client_get_lid_is_closed (UpClient *client) /** * up_client_get_can_suspend: - * @client : a #UpClient instance. + * @client: a #UpClient instance. * * Get whether the system is able to suspend. * @@ -401,7 +424,7 @@ up_client_get_can_suspend (UpClient *client) /** * up_client_get_on_battery: - * @client : a #UpClient instance. + * @client: a #UpClient instance. * * Get whether the system is running on battery power. * @@ -419,7 +442,7 @@ up_client_get_on_battery (UpClient *client) /** * up_client_get_on_low_battery: - * @client : a #UpClient instance. + * @client: a #UpClient instance. * * Get whether the system is running on low battery power. * @@ -435,9 +458,9 @@ up_client_get_on_low_battery (UpClient *client) return client->priv->on_low_battery; } -/** +/* * up_client_add: - **/ + */ static void up_client_add (UpClient *client, const gchar *object_path) { @@ -457,18 +480,18 @@ out: g_object_unref (device); } -/** +/* * up_client_added_cb: - **/ + */ static void up_device_added_cb (DBusGProxy *proxy, const gchar *object_path, UpClient *client) { up_client_add (client, object_path); } -/** +/* * up_client_changed_cb: - **/ + */ static void up_device_changed_cb (DBusGProxy *proxy, const gchar *object_path, UpClient *client) { @@ -478,9 +501,9 @@ up_device_changed_cb (DBusGProxy *proxy, const gchar *object_path, UpClient *cli g_signal_emit (client, signals [UP_CLIENT_DEVICE_CHANGED], 0, device); } -/** +/* * up_client_removed_cb: - **/ + */ static void up_device_removed_cb (DBusGProxy *proxy, const gchar *object_path, UpClient *client) { @@ -492,9 +515,9 @@ up_device_removed_cb (DBusGProxy *proxy, const gchar *object_path, UpClient *cli } } -/** +/* * up_client_changed_cb: - **/ + */ static void up_client_changed_cb (DBusGProxy *proxy, UpClient *client) { @@ -541,10 +564,10 @@ up_client_get_property (GObject *object, } } -/** +/* * up_client_class_init: * @klass: The UpClientClass - **/ + */ static void up_client_class_init (UpClientClass *klass) { @@ -652,24 +675,62 @@ up_client_class_init (UpClientClass *klass) FALSE, G_PARAM_READABLE)); + /** + * UpClient::device-added: + * @client: the #UpClient instance that emitted the signal + * @device: the #UpDevice that was added. + * + * The ::device-added signal is emitted when a power device is added. + * + * Since: 0.9.0 + **/ signals [UP_CLIENT_DEVICE_ADDED] = g_signal_new ("device-added", G_TYPE_FROM_CLASS (object_class), G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (UpClientClass, device_added), - NULL, NULL, g_cclosure_marshal_VOID__POINTER, - G_TYPE_NONE, 1, G_TYPE_POINTER); + NULL, NULL, g_cclosure_marshal_VOID__OBJECT, + G_TYPE_NONE, 1, UP_TYPE_DEVICE); + + /** + * UpClient::device-removed: + * @client: the #UpClient instance that emitted the signal + * @device: the #UpDevice that was removed. + * + * The ::device-added signal is emitted when a power device is removed. + * + * Since: 0.9.0 + **/ signals [UP_CLIENT_DEVICE_REMOVED] = g_signal_new ("device-removed", G_TYPE_FROM_CLASS (object_class), G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (UpClientClass, device_removed), - NULL, NULL, g_cclosure_marshal_VOID__POINTER, - G_TYPE_NONE, 1, G_TYPE_POINTER); + NULL, NULL, g_cclosure_marshal_VOID__OBJECT, + G_TYPE_NONE, 1, UP_TYPE_DEVICE); + + /** + * UpClient::device-changed: + * @client: the #UpClient instance that emitted the signal + * @device: the #UpDevice that was changed. + * + * The ::device-changed signal is emitted when a power device is changed. + * + * Since: 0.9.0 + **/ signals [UP_CLIENT_DEVICE_CHANGED] = g_signal_new ("device-changed", G_TYPE_FROM_CLASS (object_class), G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (UpClientClass, device_changed), - NULL, NULL, g_cclosure_marshal_VOID__POINTER, - G_TYPE_NONE, 1, G_TYPE_POINTER); + NULL, NULL, g_cclosure_marshal_VOID__OBJECT, + G_TYPE_NONE, 1, UP_TYPE_DEVICE); + + /** + * UpClient::changed: + * @client: the #UpDevice instance that emitted the signal + * + * The ::changed signal is emitted when properties may have changed. + * + * Since: 0.9.0 + **/ signals [UP_CLIENT_CHANGED] = g_signal_new ("changed", G_TYPE_FROM_CLASS (object_class), G_SIGNAL_RUN_LAST, @@ -682,6 +743,14 @@ up_client_class_init (UpClientClass *klass) /** * up_client_enumerate_devices_sync: + * @client: a #UpClient instance. + * @error: a #GError, or %NULL. + * + * Enumerates all the devices from the daemon. + * + * Return value: %TRUE for success, else %FALSE. + * + * Since: 0.9.0 **/ gboolean up_client_enumerate_devices_sync (UpClient *client, GError **error) @@ -705,10 +774,10 @@ out: return ret; } -/** +/* * up_client_init: * @client: This class instance - **/ + */ static void up_client_init (UpClient *client) { @@ -764,9 +833,9 @@ out: return; } -/** +/* * up_client_finalize: - **/ + */ static void up_client_finalize (GObject *object) { @@ -795,6 +864,8 @@ up_client_finalize (GObject *object) /** * up_client_new: * + * Creates a new #UpClient object. + * * Return value: a new UpClient object. * * Since: 0.9.0 diff --git a/libupower-glib/up-client.h b/libupower-glib/up-client.h index 743222f..bc31e12 100644 --- a/libupower-glib/up-client.h +++ b/libupower-glib/up-client.h @@ -40,7 +40,7 @@ G_BEGIN_DECLS #define UP_CLIENT_ERROR (up_client_error_quark ()) #define UP_CLIENT_TYPE_ERROR (up_client_error_get_type ()) -typedef struct UpClientPrivate UpClientPrivate; +typedef struct _UpClientPrivate UpClientPrivate; typedef struct { diff --git a/libupower-glib/up-device.c b/libupower-glib/up-device.c index 299f3a9..2213228 100644 --- a/libupower-glib/up-device.c +++ b/libupower-glib/up-device.c @@ -19,6 +19,16 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** + * SECTION:up-device + * @short_description: Client object for accessing information about UPower devices + * + * A helper GObject to use for accessing UPower devices, and to be notified + * when it is changed. + * + * See also: #UpClient + */ + #include "config.h" #include @@ -35,7 +45,12 @@ static void up_device_finalize (GObject *object); #define UP_DEVICE_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), UP_TYPE_DEVICE, UpDevicePrivate)) -struct UpDevicePrivate +/** + * UpDevicePrivate: + * + * Private #PkDevice data + **/ +struct _UpDevicePrivate { gchar *object_path; DBusGConnection *bus; @@ -113,9 +128,9 @@ static guint signals [SIGNAL_LAST] = { 0 }; G_DEFINE_TYPE (UpDevice, up_device, G_TYPE_OBJECT) -/** +/* * up_device_get_device_properties: - **/ + */ static GHashTable * up_device_get_device_properties (UpDevice *device, GError **error) { @@ -138,9 +153,9 @@ out: return hash_table; } -/** +/* * up_device_collect_props_cb: - **/ + */ static void up_device_collect_props_cb (const char *key, const GValue *value, UpDevice *device) { @@ -209,9 +224,9 @@ up_device_collect_props_cb (const char *key, const GValue *value, UpDevice *devi } } -/** +/* * up_device_refresh_internal: - **/ + */ static gboolean up_device_refresh_internal (UpDevice *device, GError **error) { @@ -230,9 +245,9 @@ up_device_refresh_internal (UpDevice *device, GError **error) return TRUE; } -/** +/* * up_device_changed_cb: - **/ + */ static void up_device_changed_cb (DBusGProxy *proxy, UpDevice *device) { @@ -325,18 +340,18 @@ up_device_get_object_path (UpDevice *device) return device->priv->object_path; } -/** +/* * up_device_bool_to_string: - **/ + */ static const gchar * up_device_bool_to_string (gboolean ret) { return ret ? "yes" : "no"; } -/** +/* * up_device_to_text_time_to_string: - **/ + */ static gchar * up_device_to_text_time_to_string (gint seconds) { @@ -359,6 +374,8 @@ up_device_to_text_time_to_string (gint seconds) /** * up_device_to_text: * + * Converts the device to a string description. + * * Return value: text representation of #UpDevice * * Since: 0.9.0 @@ -491,9 +508,9 @@ out: return ret; } -/** +/* * up_device_set_property: - **/ + */ static void up_device_set_property (GObject *object, guint prop_id, const GValue *value, GParamSpec *pspec) { @@ -593,9 +610,9 @@ up_device_set_property (GObject *object, guint prop_id, const GValue *value, GPa } } -/** +/* * up_device_get_property: - **/ + */ static void up_device_get_property (GObject *object, guint prop_id, GValue *value, GParamSpec *pspec) { @@ -689,9 +706,9 @@ up_device_get_property (GObject *object, guint prop_id, GValue *value, GParamSpe } } -/** +/* * up_device_class_init: - **/ + */ static void up_device_class_init (UpDeviceClass *klass) { @@ -701,7 +718,7 @@ up_device_class_init (UpDeviceClass *klass) object_class->get_property = up_device_get_property; /** - * PkClient::changed: + * UpDevice::changed: * @device: the #UpDevice instance that emitted the signal * * The ::changed signal is emitted when the device data has changed. @@ -718,6 +735,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:update-time: * + * The last time the device was updated. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -729,6 +748,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:vendor: * + * The vendor of the device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -740,6 +761,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:model: * + * The model of the device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -751,6 +774,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:serial: * + * The serial number of the device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -762,6 +787,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:native-path: * + * The native path of the device, useful for direct device access. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -773,6 +800,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:power-supply: * + * If the device is powering the system. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -784,6 +813,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:online: * + * If the device is online, i.e. connected. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -795,6 +826,10 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:is-present: * + * If the device is present, as some devices like laptop batteries + * can be removed, leaving an empty bay that is still technically a + * device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -806,6 +841,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:is-rechargeable: * + * If the device has a rechargable battery. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -817,6 +854,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:has-history: * + * If the device has history data that might be useful. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -828,6 +867,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:has-statistics: * + * If the device has statistics data that might be useful. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -839,6 +880,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:type: * + * The device type, e.g. %UP_DEVICE_TYPE_KEYBOARD. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -852,6 +895,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:state: * + * The state the device is in at this time, e.g. %UP_DEVICE_STATE_EMPTY. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -865,6 +910,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:technology: * + * The battery technology e.g. %UP_DEVICE_TECHNOLOGY_LITHIUM_ION. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -878,6 +925,9 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:capacity: * + * The percentage capacity of the device where 100% means the device has + * the same charge potential as when it was manufactured. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -888,6 +938,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:energy: * + * The energy left in the device. Measured in mWh. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -898,6 +950,9 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:energy-empty: * + * The energy the device will have when it is empty. This is usually zero. + * Measured in mWh. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -908,6 +963,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:energy-full: * + * The amount of energy when the device is fully charged. Measured in mWh. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -918,6 +975,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:energy-full-design: * + * The amount of energy when the device was brand new. Measured in mWh. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -928,6 +987,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:energy-rate: * + * The rate of discharge or charge. Measured in mW. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -938,6 +999,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:voltage: * + * The current voltage of the device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -948,6 +1011,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:time-to-empty: * + * The amount of time until the device is empty. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -958,6 +1023,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:time-to-full: * + * The amount of time until the device is fully charged. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -968,6 +1035,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:percentage: * + * The percentage charge of the device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -978,6 +1047,10 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:recall-notice: * + * If the device may be recalled due to defect. NOTE: This property does + * not mean the battery is broken, and just that the user should + * _check_ with the vendor. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -989,6 +1062,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:recall-vendor: * + * The vendor that is recalling the device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -1000,6 +1075,8 @@ up_device_class_init (UpDeviceClass *klass) /** * UpDevice:recall-url: * + * The vendors internet link for the recalled device. + * * Since: 0.9.0 **/ g_object_class_install_property (object_class, @@ -1012,9 +1089,9 @@ up_device_class_init (UpDeviceClass *klass) g_type_class_add_private (klass, sizeof (UpDevicePrivate)); } -/** +/* * up_device_init: - **/ + */ static void up_device_init (UpDevice *device) { @@ -1024,9 +1101,9 @@ up_device_init (UpDevice *device) device->priv->proxy_props = NULL; } -/** +/* * up_device_finalize: - **/ + */ static void up_device_finalize (GObject *object) { @@ -1054,6 +1131,8 @@ up_device_finalize (GObject *object) /** * up_device_new: * + * Creates a new #UpDevice object. + * * Return value: a new UpDevice object. * * Since: 0.9.0 diff --git a/libupower-glib/up-device.h b/libupower-glib/up-device.h index f9b2db4..d29a5a0 100644 --- a/libupower-glib/up-device.h +++ b/libupower-glib/up-device.h @@ -40,7 +40,7 @@ G_BEGIN_DECLS #define UP_DEVICE_ERROR (up_device_error_quark ()) #define UP_DEVICE_TYPE_ERROR (up_device_error_get_type ()) -typedef struct UpDevicePrivate UpDevicePrivate; +typedef struct _UpDevicePrivate UpDevicePrivate; typedef struct { @@ -76,14 +76,6 @@ gboolean up_device_refresh_sync (UpDevice *device, gboolean up_device_set_object_path_sync (UpDevice *device, const gchar *object_path, GError **error); -GPtrArray *up_device_get_history_sync (UpDevice *device, - const gchar *type, - guint timespec, - guint resolution, - GError **error); -GPtrArray *up_device_get_statistics_sync (UpDevice *device, - const gchar *type, - GError **error); /* accessors */ const gchar *up_device_get_object_path (UpDevice *device); diff --git a/libupower-glib/up-types.c b/libupower-glib/up-types.c index 406b346..66aa637 100644 --- a/libupower-glib/up-types.c +++ b/libupower-glib/up-types.c @@ -19,6 +19,16 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** + * SECTION:up-types + * @short_description: Types used by UPower and libupower-glib + * + * These helper functions provide a way to marshal enumerated values to + * text and back again. + * + * See also: #UpClient, #UpDevice + */ + #include "config.h" #include diff --git a/libupower-glib/up-types.h b/libupower-glib/up-types.h index 05f25b2..2685d9b 100644 --- a/libupower-glib/up-types.h +++ b/libupower-glib/up-types.h @@ -30,6 +30,11 @@ G_BEGIN_DECLS +/** + * UpDeviceType: + * + * The device type. + **/ typedef enum { UP_DEVICE_TYPE_UNKNOWN, UP_DEVICE_TYPE_LINE_POWER, @@ -43,6 +48,11 @@ typedef enum { UP_DEVICE_TYPE_LAST } UpDeviceType; +/** + * UpDeviceState: + * + * The device state. + **/ typedef enum { UP_DEVICE_STATE_UNKNOWN, UP_DEVICE_STATE_CHARGING, @@ -54,6 +64,11 @@ typedef enum { UP_DEVICE_STATE_LAST } UpDeviceState; +/** + * UpDeviceTechnology: + * + * The device technology. + **/ typedef enum { UP_DEVICE_TECHNOLOGY_UNKNOWN, UP_DEVICE_TECHNOLOGY_LITHIUM_ION, @@ -65,6 +80,11 @@ typedef enum { UP_DEVICE_TECHNOLOGY_LAST } UpDeviceTechnology; +/** + * UpQosType: + * + * The type of QOS request. + **/ typedef enum { UP_QOS_TYPE_UNKNOWN, UP_QOS_TYPE_NETWORK, diff --git a/libupower-glib/up-version.h.in b/libupower-glib/up-version.h.in index 2a89c50..149703e 100644 --- a/libupower-glib/up-version.h.in +++ b/libupower-glib/up-version.h.in @@ -19,6 +19,16 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** + * SECTION:up-version + * @short_description: Obtains the version for the installed UPower + * + * These compile time macros allow the user to enable parts of client code + * depending on the version of libupower-glib installed. + * + * See also: #UpClient, #UpDevice + */ + #if !defined (__UPOWER_H_INSIDE__) && !defined (UP_COMPILATION) #error "Only can be included directly." #endif @@ -26,14 +36,34 @@ #ifndef __UP_VERSION_H #define __UP_VERSION_H -/* compile time version +/** + * UP_CHECK_VERSION: + * + * The compile-time major version + */ +#define UP_MAJOR_VERSION (@UP_MAJOR_VERSION@) + +/** + * UP_CHECK_MINOR: + * + * The compile-time minor version + */ +#define UP_MINOR_VERSION (@UP_MINOR_VERSION@) + +/** + * UP_MICRO_VERSION: + * + * The compile-time micro version */ -#define UP_COMPILE_VERSION (0x@VERSION@) +#define UP_MICRO_VERSION (@UP_MICRO_VERSION@) -/* check whether a the version is above the compile time version. +/* check whether a UPower version equal to or greater than + * major.minor.micro. */ -#define UP_CHECK_VERSION(ver) \ - (UP_COMPILE_VERSION > (ver) || \ - (UP_COMPILE_VERSION == (ver))) +#define UP_CHECK_VERSION(major,minor,micro) \ + (UP_MAJOR_VERSION > (major) || \ + (UP_MAJOR_VERSION == (major) && UP_MINOR_VERSION > (minor)) || \ + (UP_MAJOR_VERSION == (major) && UP_MINOR_VERSION == (minor) && \ + UP_MICRO_VERSION >= (micro))) #endif /* __UP_VERSION_H */ diff --git a/libupower-glib/upower.h b/libupower-glib/upower.h index f9a1e7c..5c91623 100644 --- a/libupower-glib/upower.h +++ b/libupower-glib/upower.h @@ -19,6 +19,16 @@ * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** + * SECTION:upower + * @short_description: Client objects for accessing UPower + * + * These objects allow client programs to trivially get details about the power + * state, and about devices on the system. + * + * See also: #UpClient, #UpDevice + */ + #ifndef __UPOWER_H__ #define __UPOWER_H__ diff --git a/po/it.po b/po/it.po index 9ddc4e9..008a35e 100644 --- a/po/it.po +++ b/po/it.po @@ -1,4 +1,4 @@ -# Italian translation for DeviceKit-power +# Italian translation for UPower # Copyright (C) 2009 The Free Software Foundation, Inc # This file is distributed under the same license as the PolicyKit package. # Luca Ferretti , 2009. @@ -6,7 +6,7 @@ # Milo Casagrande , 2009. msgid "" msgstr "" -"Project-Id-Version: DeviceKit-power 011\n" +"Project-Id-Version: UPower 011\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2009-08-24 13:05+0200\n" "PO-Revision-Date: 2009-08-26 21:05+0200\n" -- cgit v1.2.1