Skip to content

GitLab

U
upower
Commit 27fada20 authored by Richard Hughes's avatar Richard Hughes
Browse files
Options

trivial: add some gtk-doc markup into libupower-glib and hook it up to the build system

parent 69c06340
Hide whitespace changes
Inline Side-by-side
Showing with 342 additions and 106 deletions
configure.ac
View file @ 27fada20
......@@ -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}
......
devkit-power-gobject/dkp-version.h.in
View file @ 27fada20
......@@ -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 */
doc/.gitignore
View file @ 27fada20
......@@ -12,4 +12,5 @@ html
tmpl
version.xml
xml
.libs
doc/Makefile.am
View file @ 27fada20
......@@ -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)
......
doc/upower-docs.xml
View file @ 27fada20
......@@ -9,13 +9,13 @@
<releaseinfo>Version &version;</releaseinfo>
<authorgroup>
<author>
<firstname>David</firstname>
<surname>Zeuthen</surname>
<affiliation>
<address>
<email>davidz@redhat.com</email>
</address>
</affiliation>
<firstname>Richard</firstname>
<surname>Hughes</surname>
<affiliation>
<address>
<email>richard@hughsie.com</email>
</address>
</affiliation>
</author>
</authorgroup>
......@@ -69,6 +69,27 @@
<xi:include href="dbus/org.freedesktop.UPower.QoS.ref.xml"/>
</reference>
<reference id="libupower-glib">
<title>libpackagekit GObjects</title>
<partintro>
<para>
This part documents GObjects used in libupower-glib.
</para>
</partintro>
<xi:include href="xml/up-client.xml"/>
<xi:include href="xml/up-device.xml"/>
</reference>
<reference id="libupower-glib-helpers">
<title>libupower-glib helpers</title>
<partintro>
<para>
This part documents helper funtions in libupower-glib.
</para>
</partintro>
<xi:include href="xml/up-types.xml"/>
</reference>
<reference id="tools-fileformats">
<title>Manual Pages</title>
<partintro>
......
libupower-glib/Makefile.am
View file @ 27fada20
......@@ -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)
......
libupower-glib/up-client.c
View file @ 27fada20
......@@ -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 <stdlib.h>
......@@ -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
......
libupower-glib/up-client.h
View file @ 27fada20
......@@ -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
{
......
libupower-glib/up-device.c
View file @ 27fada20
......@@ -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 <stdlib.h>
......@@ -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.
*