GNOME.org
 

[gnome-color-manager: 72/80] trivial: add a shitload more gtk-doc markup, loads more to come

commit 2a4417bda91d4388eb222434774b058e552e2b3c
Author: Richard Hughes <richard hughsie com>
Date:   Sun Jul 18 19:38:30 2010 +0100

    trivial: add a shitload more gtk-doc markup, loads more to come

 docs/api/Makefile.am              |    6 +-
 docs/api/clean.sh                 |    7 ++
 docs/api/libcolor-glib-docs.sgml  |   51 ++++++++++++--
 libcolor-glib/gcm-ddc-control.c   |   78 +++++++++++++++++++-
 libcolor-glib/gcm-ddc-device.c    |  114 ++++++++++++++++++++++++++++-
 libcolor-glib/gcm-ddc-device.h    |    5 ++
 libcolor-glib/gcm-image.c         |    6 +-
 libcolor-glib/gcm-profile-store.c |   25 ++++++-
 libcolor-glib/gcm-profile.c       |  142 +++++++++++++++++++++++++++++++++++--
 libcolor-glib/gcm-xserver.c       |   55 +++++++++++---
 10 files changed, 450 insertions(+), 39 deletions(-)
---
diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am
index f0e83cd..088fe7e 100644
--- a/docs/api/Makefile.am
+++ b/docs/api/Makefile.am
@@ -55,18 +55,16 @@ expand_content_files=
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget
 # signals and properties.
 INCLUDES =						\
-	$(POLKIT_CFLAGS)				\
-	$(DBUS_CFLAGS)					\
 	$(GLIB_CFLAGS)					\
 	-I$(top_builddir)/libcolor-glib			\
 	-I$(top_srcdir)/libcolor-glib
 
-GCM_GLIB_LIBS =					\
+LIBCOLOR_GLIB_LIBS =					\
 	$(top_builddir)/libcolor-glib/libcolor-glib.la
 
 GTKDOC_LIBS =						\
 	$(GLIB_LIBS)					\
-	$(GCM_GLIB_LIBS)
+	$(LIBCOLOR_GLIB_LIBS)
 
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make
diff --git a/docs/api/clean.sh b/docs/api/clean.sh
new file mode 100755
index 0000000..b90dd93
--- /dev/null
+++ b/docs/api/clean.sh
@@ -0,0 +1,7 @@
+rm -f *.txt
+rm -f PackageKit-scan.*
+rm -f PackageKit.types
+rm -f html/*.html
+rm -f html/*.png
+rm -f tmpl/*
+
diff --git a/docs/api/libcolor-glib-docs.sgml b/docs/api/libcolor-glib-docs.sgml
index 3ebca55..524e05d 100644
--- a/docs/api/libcolor-glib-docs.sgml
+++ b/docs/api/libcolor-glib-docs.sgml
@@ -6,22 +6,63 @@
 ]>
 <book id="index">
   <bookinfo>
-    <title>gcm Reference Manual</title>
+    <title>GNOME Color Manager Reference Manual</title>
     <releaseinfo>
-      for gcm [VERSION].
+      for gnome-color-manager 2.31.x.
       The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://[SERVER]/gcm/index.html";>http://[SERVER]/gcm/</ulink>.
+      <ulink role="online-location" url="http://projects.gnome.org/gnome-color-manager/libcolor-glib/index.html";>projects.gnome.org</ulink>.
     </releaseinfo>
+    <authorgroup>
+      <author>
+        <firstname>Richard</firstname>
+        <surname>Hughes</surname>
+        <affiliation>
+          <address>
+            <email>richard hughsie com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+    <copyright>
+      <year>2010</year>
+      <holder>Richard Hughes</holder>
+    </copyright>
   </bookinfo>
 
   <chapter>
-    <title>[Insert title here]</title>
+    <title>libcolor-glib objects</title>
+<!--
     <xi:include href="xml/gcm-device.xml"/>
     <xi:include href="xml/gcm-client.xml"/>
+-->
+    <xi:include href="xml/gcm-sensor-dummy.xml"/>
+    <xi:include href="xml/gcm-xserver.xml"/>
+    <xi:include href="xml/gcm-edid.xml"/>
+    <xi:include href="xml/gcm-ddc-control.xml"/>
+    <xi:include href="xml/gcm-profile.xml"/>
+    <xi:include href="xml/gcm-clut.xml"/>
+    <xi:include href="xml/gcm-tables.xml"/>
+    <xi:include href="xml/gcm-ddc-device.xml"/>
+    <xi:include href="xml/gcm-sensor-client.xml"/>
+    <xi:include href="xml/gcm-image.xml"/>
+    <xi:include href="xml/gcm-sensor-huey.xml"/>
+    <xi:include href="xml/gcm-profile-store.xml"/>
+    <xi:include href="xml/gcm-sensor.xml"/>
+    <xi:include href="xml/gcm-dmi.xml"/>
+    <xi:include href="xml/gcm-brightness.xml"/>
+    <xi:include href="xml/gcm-xyz.xml"/>
+    <xi:include href="xml/gcm-ddc-client.xml"/>
+
+  </chapter>
+
+  <chapter>
+    <title>libcolor-glib helpers</title>
+    <xi:include href="xml/egg-debug.xml"/>
     <xi:include href="xml/gcm-version.xml"/>
     <xi:include href="xml/gcm-common.xml"/>
-
+    <xi:include href="xml/gcm-ddc-common.xml"/>
   </chapter>
+
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
diff --git a/libcolor-glib/gcm-ddc-control.c b/libcolor-glib/gcm-ddc-control.c
index 3e51a31..3cb724a 100644
--- a/libcolor-glib/gcm-ddc-control.c
+++ b/libcolor-glib/gcm-ddc-control.c
@@ -64,6 +64,13 @@ G_DEFINE_TYPE (GcmDdcControl, gcm_ddc_control, G_TYPE_OBJECT)
 
 /**
  * gcm_ddc_control_get_description:
+ * @control: A valid #GcmDdcControl
+ *
+ * Gets the string description for the control.
+ *
+ * Return value: A string value, or %NULL
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_ddc_control_get_description (GcmDdcControl *control)
@@ -112,8 +119,15 @@ out:
 
 /**
  * gcm_ddc_control_set:
+ * @control: A valid #GcmDdcControl
+ * @value: the value to write
+ * @error: a #GError, or %NULL
+ *
+ * Sets the control value.
  *
- * write value to register ctrl of ddc/ci
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_control_set (GcmDdcControl *control, guint16 value, GError **error)
@@ -146,6 +160,14 @@ out:
 
 /**
  * gcm_ddc_control_reset:
+ * @control: A valid #GcmDdcControl
+ * @error: a #GError, or %NULL
+ *
+ * Resets the control to it's default value.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_control_reset (GcmDdcControl *control, GError **error)
@@ -171,6 +193,16 @@ out:
 
 /**
  * gcm_ddc_control_request:
+ * @control: A valid #GcmDdcControl
+ * @value: the value location to write into
+ * @maximum: the value maximum location to write into
+ * @error: a #GError, or %NULL
+ *
+ * Get the value of this control.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_control_request (GcmDdcControl *control, guint16 *value, guint16 *maximum, GError **error)
@@ -235,6 +267,15 @@ out:
 
 /**
  * gcm_ddc_control_run:
+ * @control: A valid #GcmDdcControl
+ * @error: a #GError, or %NULL
+ *
+ * Runs the control. Note, this only makes sense for true controls like 'degauss'
+ * rather than other VCP values such as 'contrast'.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_control_run (GcmDdcControl *control, GError **error)
@@ -250,6 +291,13 @@ gcm_ddc_control_run (GcmDdcControl *control, GError **error)
 
 /**
  * gcm_ddc_control_parse:
+ * @control: A valid #GcmDdcControl
+ * @id: the control ID, e.g. %GCM_DDC_CONTROL_ID_BRIGHTNESS
+ * @values: a string of permissible values, e.g. "1 3 5 7 8 9" or %NULL
+ *
+ * Parses a control string for permissable values.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_ddc_control_parse (GcmDdcControl *control, guchar id, const gchar *values)
@@ -283,6 +331,12 @@ out:
 
 /**
  * gcm_ddc_control_set_device:
+ * @control: A valid #GcmDdcControl
+ * @device: the device that owns this control.
+ *
+ * Set the device that this control belongs to.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_ddc_control_set_device (GcmDdcControl *control, GcmDdcDevice *device)
@@ -294,6 +348,13 @@ gcm_ddc_control_set_device (GcmDdcControl *control, GcmDdcDevice *device)
 
 /**
  * gcm_ddc_control_get_id:
+ * @control: A valid #GcmDdcControl
+ *
+ * Gets the ID for this control.
+ *
+ * Return value: The control ID, e.g. GCM_DDC_CONTROL_ID_BRIGHTNESS
+ *
+ * Since: 0.0.1
  **/
 guchar
 gcm_ddc_control_get_id (GcmDdcControl *control)
@@ -305,8 +366,13 @@ gcm_ddc_control_get_id (GcmDdcControl *control)
 
 /**
  * gcm_ddc_control_get_values:
+ * @control: A valid #GcmDdcControl
+ *
+ * Gets the permissible values of this control.
+ *
+ * Return value: A GArray of guint16 values, free with g_array_unref().
  *
- * Return value: an array of guint16
+ * Since: 0.0.1
  **/
 GArray *
 gcm_ddc_control_get_values (GcmDdcControl *control)
@@ -318,6 +384,12 @@ gcm_ddc_control_get_values (GcmDdcControl *control)
 
 /**
  * gcm_ddc_control_set_verbose:
+ * @control: A valid #GcmDdcControl
+ * @verbose: if the control should log to stderr.
+ *
+ * Set the control verbosity.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_ddc_control_set_verbose (GcmDdcControl *control, GcmVerbose verbose)
@@ -431,7 +503,7 @@ gcm_ddc_control_finalize (GObject *object)
 /**
  * gcm_ddc_control_new:
  *
- * GcmDdcControl is a nice GObject wrapper for gcm.
+ * Get a control objects.
  *
  * Return value: A new %GcmDdcControl instance
  *
diff --git a/libcolor-glib/gcm-ddc-device.c b/libcolor-glib/gcm-ddc-device.c
index 912c04a..a115a7e 100644
--- a/libcolor-glib/gcm-ddc-device.c
+++ b/libcolor-glib/gcm-ddc-device.c
@@ -23,7 +23,7 @@
  * SECTION:gcm-ddc-device
  * @short_description: For managing different i2c devices
  *
- * A GObject to use for accessing devices.
+ * A GObject to use for accessing a device using I2C.
  */
 
 #include "config.h"
@@ -287,8 +287,14 @@ gcm_ddc_device_wait_for_hardware (GcmDdcDevice *device)
 
 /**
  * gcm_ddc_device_write:
+ * @device: A valid #GcmDdcDevice
+ * @data: the data to write
+ * @length: the length of the data to write
+ * @error: a #GError, or %NULL
  *
- * write data to ddc/ci at address addr
+ * Write data to DDC/CI at previoulsly set address address.
+ *
+ * Return value: %TRUE for success
  **/
 gboolean
 gcm_ddc_device_write (GcmDdcDevice *device, guchar *data, gsize length, GError **error)
@@ -334,7 +340,17 @@ out:
 /**
  * gcm_ddc_device_read:
  *
- * Read ddc/ci formatted frame from ddc/ci
+ * @device: A valid #GcmDdcDevice
+ * @data: the data location to read into
+ * @length: the length of the @data buffer
+ * @recieved_length: the amount of data that was copied
+ * @error: a #GError, or %NULL
+ *
+ * Read DDC/CI formatted frame from the device.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_device_read (GcmDdcDevice *device, guchar *data, gsize data_length, gsize *recieved_length, GError **error)
@@ -407,7 +423,7 @@ out:
 /**
  * gcm_ddc_device_capabilities_request:
  *
- * read capabilities raw data of ddc/ci
+ * Read capabilities raw data of ddc/ci
  **/
 static gint
 gcm_ddc_device_capabilities_request (GcmDdcDevice *device, guint offset, guchar *data, gsize data_length, gsize *recieved_length, GError **error)
@@ -607,6 +623,15 @@ out:
 
 /**
  * gcm_ddc_device_save:
+ *
+ * @device: A valid #GcmDdcDevice
+ * @error: a #GError, or %NULL
+ *
+ * Saves any state to the device EEPROM.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_device_save (GcmDdcDevice *device, GError **error)
@@ -661,6 +686,14 @@ out:
 
 /**
  * gcm_ddc_device_close:
+ * @device: A valid #GcmDdcDevice
+ * @error: a #GError, or %NULL
+ *
+ * Close the device, and returning control back to the OSD.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_device_close (GcmDdcDevice *device, GError **error)
@@ -685,6 +718,15 @@ out:
 
 /**
  * gcm_ddc_device_open:
+ * @device: A valid #GcmDdcDevice
+ * @filename: the device node, e.g. "/dev/ddc-1"
+ * @error: a #GError, or %NULL
+ *
+ * Open a device, and take control of the OSD if possible.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_ddc_device_open (GcmDdcDevice *device, const gchar *filename, GError **error)
@@ -727,6 +769,14 @@ out:
 
 /**
  * gcm_ddc_device_get_controls:
+ * @device: A valid #GcmDdcDevice
+ * @error: a #GError, or %NULL
+ *
+ * Get the list of controls for this device.
+ *
+ * Return value: A #GPtrArray of #GcmDdcControl's, free with g_ptr_array_unref() when done.
+ *
+ * Since: 0.0.1
  **/
 GPtrArray *
 gcm_ddc_device_get_controls (GcmDdcDevice *device, GError **error)
@@ -750,6 +800,15 @@ out:
 
 /**
  * gcm_ddc_device_get_control_by_id:
+ * @device: A valid #GcmDdcDevice
+ * @id: the device ID, e.g. GCM_DDC_CONTROL_ID_BRIGHTNESS
+ * @error: a #GError, or %NULL
+ *
+ * Gets a #GcmControl object from the ID.
+ *
+ * Return value: %NULL, or a #GcmControl which needs to be freed with g_object_unref().
+ *
+ * Since: 0.0.1
  **/
 GcmDdcControl *
 gcm_ddc_device_get_control_by_id (GcmDdcDevice *device, guchar id, GError **error)
@@ -787,6 +846,15 @@ out:
 
 /**
  * gcm_ddc_device_get_edid:
+ * @device: A valid #GcmDdcDevice
+ * @length: the length of the return buffer, or %NULL
+ * @error: a #GError, or %NULL
+ *
+ * Gets the raw EDID data for the device.
+ *
+ * Return value: a pointer to the EDID block. Do not free this value.
+ *
+ * Since: 0.0.1
  **/
 const guint8 *
 gcm_ddc_device_get_edid	(GcmDdcDevice *device, gsize *length, GError **error)
@@ -812,6 +880,14 @@ out:
 
 /**
  * gcm_ddc_device_get_edid_md5:
+ * @device: A valid #GcmDdcDevice
+ * @error: a #GError, or %NULL
+ *
+ * Gets the MD5 of the EDID.
+ *
+ * Return value: The MD5 value of the current EDID. Do not free this value.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_ddc_device_get_edid_md5 (GcmDdcDevice *device, GError **error)
@@ -835,6 +911,14 @@ out:
 
 /**
  * gcm_ddc_device_get_pnpid:
+ * @device: A valid #GcmDdcDevice
+ * @error: a #GError, or %NULL
+ *
+ * Gets the PNPID for the device.
+ *
+ * Return value: The PNPID, or %NULL.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_ddc_device_get_pnpid (GcmDdcDevice	*device, GError **error)
@@ -858,6 +942,14 @@ out:
 
 /**
  * gcm_ddc_device_get_model:
+ * @device: A valid #GcmDdcDevice
+ * @error: a #GError, or %NULL
+ *
+ * Gets the model of the device.
+ *
+ * Return value: The model string, or %NULL.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_ddc_device_get_model (GcmDdcDevice	*device, GError **error)
@@ -881,6 +973,14 @@ out:
 
 /**
  * gcm_ddc_device_get_kind:
+ * @device: A valid #GcmDdcDevice
+ * @error: a #GError, or %NULL
+ *
+ * Gets the device kind.
+ *
+ * Return value: The device kind, e.g. GCM_DDC_DEVICE_KIND_LCD, or %GCM_DDC_DEVICE_KIND_UNKNOWN for an error.
+ *
+ * Since: 0.0.1
  **/
 GcmDdcDeviceKind
 gcm_ddc_device_get_kind (GcmDdcDevice *device, GError **error)
@@ -904,6 +1004,12 @@ out:
 
 /**
  * gcm_ddc_device_set_verbose:
+ * @device: A valid #GcmDdcDevice
+ * @verbose: if we should print out debugging to the console
+ *
+ * Sets the logging mode of the device. By default we log nothing.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_ddc_device_set_verbose (GcmDdcDevice *device, GcmVerbose verbose)
diff --git a/libcolor-glib/gcm-ddc-device.h b/libcolor-glib/gcm-ddc-device.h
index c6e60c8..a4db08c 100644
--- a/libcolor-glib/gcm-ddc-device.h
+++ b/libcolor-glib/gcm-ddc-device.h
@@ -78,6 +78,11 @@ struct _GcmDdcDeviceClass
 	void (*_gcm_reserved5) (void);
 };
 
+/**
+ * GcmDdcDeviceKind:
+ *
+ * The device type
+ **/
 typedef enum {
 	GCM_DDC_DEVICE_KIND_LCD,
 	GCM_DDC_DEVICE_KIND_CRT,
diff --git a/libcolor-glib/gcm-image.c b/libcolor-glib/gcm-image.c
index c7651be..4a6d8ad 100644
--- a/libcolor-glib/gcm-image.c
+++ b/libcolor-glib/gcm-image.c
@@ -20,10 +20,10 @@
  */
 
 /**
- * SECTION:gcm-image-manual
- * @short_description: routines to manually create a color profile.
+ * SECTION:gcm-image
+ * @short_description: a color managed #GtkImage.
  *
- * This object can create an ICC file manually.
+ * This object is used to convert an image using one, two or three ICC profiles.
  */
 
 #include "config.h"
diff --git a/libcolor-glib/gcm-profile-store.c b/libcolor-glib/gcm-profile-store.c
index 71f0e56..2e6c464 100644
--- a/libcolor-glib/gcm-profile-store.c
+++ b/libcolor-glib/gcm-profile-store.c
@@ -66,12 +66,13 @@ G_DEFINE_TYPE (GcmProfileStore, gcm_profile_store, G_TYPE_OBJECT)
 
 /**
  * gcm_profile_store_get_array:
- *
  * @profile_store: a valid %GcmProfileStore instance
  *
  * Gets the profile list.
  *
  * Return value: an array, free with g_ptr_array_unref()
+ *
+ * Since: 0.0.1
  **/
 GPtrArray *
 gcm_profile_store_get_array (GcmProfileStore *profile_store)
@@ -99,13 +100,14 @@ gcm_profile_store_in_array (GPtrArray *array, const gchar *text)
 
 /**
  * gcm_profile_store_get_by_filename:
- *
  * @profile_store: a valid %GcmProfileStore instance
  * @filename: the profile filename
  *
  * Gets a profile.
  *
  * Return value: a valid %GcmProfile or %NULL. Free with g_object_unref()
+ *
+ * Since: 0.0.1
  **/
 GcmProfile *
 gcm_profile_store_get_by_filename (GcmProfileStore *profile_store, const gchar *filename)
@@ -134,13 +136,14 @@ out:
 
 /**
  * gcm_profile_store_get_by_checksum:
- *
  * @profile_store: a valid %GcmProfileStore instance
  * @checksum: the profile checksum
  *
  * Gets a profile.
  *
  * Return value: a valid %GcmProfile or %NULL. Free with g_object_unref()
+ *
+ * Since: 0.0.1
  **/
 GcmProfile *
 gcm_profile_store_get_by_checksum (GcmProfileStore *profile_store, const gchar *checksum)
@@ -303,8 +306,14 @@ out:
 
 /**
  * gcm_profile_store_search_path:
+ * @profile_store: a valid %GcmProfileStore instance
+ * @path: the filesystem path to search
+ *
+ * Searches a specified location for ICC profiles.
  *
  * Return value: if any profile were added
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_profile_store_search_path (GcmProfileStore *profile_store, const gchar *path)
@@ -503,8 +512,14 @@ out:
 
 /**
  * gcm_profile_store_search:
+ * @profile_store: a valid %GcmProfileStore instance
+ * @flags: the #GcmProfileSearchFlags locations to search
  *
- * Return value: if any profile were added
+ * Searches specified locations for ICC profiles.
+ *
+ * Return value: %TRUE if any profile were added
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_profile_store_search (GcmProfileStore *profile_store, GcmProfileSearchFlags flags)
@@ -666,6 +681,8 @@ gcm_profile_store_finalize (GObject *object)
  * gcm_profile_store_new:
  *
  * Return value: a new GcmProfileStore object.
+ *
+ * Since: 0.0.1
  **/
 GcmProfileStore *
 gcm_profile_store_new (void)
diff --git a/libcolor-glib/gcm-profile.c b/libcolor-glib/gcm-profile.c
index a86395e..c3ae0dd 100644
--- a/libcolor-glib/gcm-profile.c
+++ b/libcolor-glib/gcm-profile.c
@@ -106,6 +106,13 @@ static void gcm_profile_file_monitor_changed_cb (GFileMonitor *monitor, GFile *f
 
 /**
  * gcm_profile_get_description:
+ * @profile: A valid #GcmProfile
+ *
+ * Gets the profile description.
+ *
+ * Return value: The profile description as a string.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_profile_get_description (GcmProfile *profile)
@@ -140,6 +147,12 @@ gcm_profile_ensure_printable (gchar *text)
 
 /**
  * gcm_profile_set_description:
+ * @profile: A valid #GcmProfile
+ * @description: the data location to read into
+ *
+ * Sets the description of the profile.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_profile_set_description (GcmProfile *profile, const gchar *description)
@@ -168,9 +181,14 @@ gcm_profile_set_description (GcmProfile *profile, const gchar *description)
 
 /**
  * gcm_profile_has_colorspace_description:
+ * @profile: A valid #GcmProfile
+ *
+ * Finds out if the profile contains a colorspace description.
  *
- * Return value: if the description mentions the profile colorspace explicity,
+ * Return value: %TRUE if the description mentions the profile colorspace explicity,
  * e.g. "Adobe RGB" for %GCM_COLORSPACE_RGB.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_profile_has_colorspace_description (GcmProfile *profile)
@@ -190,8 +208,13 @@ gcm_profile_has_colorspace_description (GcmProfile *profile)
 
 /**
  * gcm_profile_get_file:
+ * @profile: A valid #GcmProfile
  *
- * Return value: Do not unref.
+ * Gets the file attached to this profile.
+ *
+ * Return value: A #GFile, or %NULL. Do not free.
+ *
+ * Since: 0.0.1
  **/
 GFile *
 gcm_profile_get_file (GcmProfile *profile)
@@ -202,6 +225,14 @@ gcm_profile_get_file (GcmProfile *profile)
 
 /**
  * gcm_profile_set_file:
+ * @profile: A valid #GcmProfile
+ * @file: A #GFile to read
+ *
+ * Sets the file to be used when reading the profile.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_profile_set_file (GcmProfile *profile, GFile *file)
@@ -231,6 +262,13 @@ gcm_profile_set_file (GcmProfile *profile, GFile *file)
 
 /**
  * gcm_profile_get_filename:
+ * @profile: A valid #GcmProfile
+ *
+ * Gets the filename of the profile data, if one exists.
+ *
+ * Return value: A filename, or %NULL
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_profile_get_filename (GcmProfile *profile)
@@ -247,6 +285,13 @@ gcm_profile_get_filename (GcmProfile *profile)
 
 /**
  * gcm_profile_get_copyright:
+ * @profile: A valid #GcmProfile
+ *
+ * Gets the copyright string for this profile.
+ *
+ * Return value: A string. Do not free.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_profile_get_copyright (GcmProfile *profile)
@@ -257,6 +302,12 @@ gcm_profile_get_copyright (GcmProfile *profile)
 
 /**
  * gcm_profile_set_copyright:
+ * @profile: A valid #GcmProfile
+ * @copyright: the copyright string
+ *
+ * Sets the copyright string.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_profile_set_copyright (GcmProfile *profile, const gchar *copyright)
@@ -274,6 +325,13 @@ gcm_profile_set_copyright (GcmProfile *profile, const gchar *copyright)
 
 /**
  * gcm_profile_get_model:
+ * @profile: A valid #GcmProfile
+ *
+ * Gets the device model name.
+ *
+ * Return value: A string. Do not free.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_profile_get_model (GcmProfile *profile)
@@ -284,6 +342,12 @@ gcm_profile_get_model (GcmProfile *profile)
 
 /**
  * gcm_profile_set_model:
+ * @profile: A valid #GcmProfile
+ * @model: the profile model.
+ *
+ * Sets the device model name.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_profile_set_model (GcmProfile *profile, const gchar *model)
@@ -301,6 +365,13 @@ gcm_profile_set_model (GcmProfile *profile, const gchar *model)
 
 /**
  * gcm_profile_get_manufacturer:
+ * @profile: A valid #GcmProfile
+ *
+ * Gets the device manufacturer name.
+ *
+ * Return value: A string. Do not free.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_profile_get_manufacturer (GcmProfile *profile)
@@ -311,6 +382,12 @@ gcm_profile_get_manufacturer (GcmProfile *profile)
 
 /**
  * gcm_profile_set_manufacturer:
+ * @profile: A valid #GcmProfile
+ * @model: the profile manufacturer.
+ *
+ * Sets the device manufacturer name.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_profile_set_manufacturer (GcmProfile *profile, const gchar *manufacturer)
@@ -328,6 +405,13 @@ gcm_profile_set_manufacturer (GcmProfile *profile, const gchar *manufacturer)
 
 /**
  * gcm_profile_get_datetime:
+ * @profile: A valid #GcmProfile
+ *
+ * Gets the profile date and time.
+ *
+ * Return value: A string. Do not free.
+ *
+ * Since: 0.0.1
  **/
 const gchar *
 gcm_profile_get_datetime (GcmProfile *profile)
@@ -338,6 +422,12 @@ gcm_profile_get_datetime (GcmProfile *profile)
 
 /**
  * gcm_profile_set_datetime:
+ * @profile: A valid #GcmProfile
+ * @datetime: the profile date time.
+ *
+ * Sets the profile date and time.
+ *
+ * Since: 0.0.1
  **/
 void
 gcm_profile_set_datetime (GcmProfile *profile, const gchar *datetime)
@@ -498,6 +588,16 @@ gcm_utils_format_date_time (const struct tm *created)
 
 /**
  * gcm_profile_parse_data:
+ * @profile: A valid #GcmProfile
+ * @data: the data to parse
+ * @length: the length of @data
+ * @error: A #GError, or %NULL
+ *
+ * Parses profile data, filling in all the details possible.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_profile_parse_data (GcmProfile *profile, const guint8 *data, gsize length, GError **error)
@@ -757,6 +857,15 @@ out:
 
 /**
  * gcm_profile_parse:
+ * @profile: A valid #GcmProfile
+ * @file: A GFile pointing to a profile
+ * @error: A #GError, or %NULL
+ *
+ * Parses a profile filename, filling in all the details possible.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_profile_parse (GcmProfile *profile, GFile *file, GError **error)
@@ -801,6 +910,15 @@ out:
 
 /**
  * gcm_profile_save:
+ * @profile: A valid #GcmProfile
+ * @filename: the data to parse
+ * @error: A #GError, or %NULL
+ *
+ * Saves the profile data to a file.
+ *
+ * Return value: %TRUE for success
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_profile_save (GcmProfile *profile, const gchar *filename, GError **error)
@@ -823,8 +941,14 @@ out:
 
 /**
  * gcm_profile_generate_vcgt:
+ * @profile: A valid #GcmProfile
+ * @size: the size of the table to generate
+ *
+ * Generates a VCGT table of a specified size.
+ *
+ * Return value: A #GcmClut object, or %NULL. Free with g_object_unref()
  *
- * Free with g_object_unref();
+ * Since: 0.0.1
  **/
 GcmClut *
 gcm_profile_generate_vcgt (GcmProfile *profile, guint size)
@@ -866,8 +990,14 @@ out:
 
 /**
  * gcm_profile_generate_curve:
+ * @profile: A valid #GcmProfile
+ * @size: the size of the curve to generate
  *
- * Free with g_object_unref();
+ * Generates a curve of a specified size.
+ *
+ * Return value: A #GcmClut object, or %NULL. Free with g_object_unref()
+ *
+ * Since: 0.0.1
  **/
 GcmClut *
 gcm_profile_generate_curve (GcmProfile *profile, guint size)
@@ -1329,7 +1459,9 @@ gcm_profile_finalize (GObject *object)
 /**
  * gcm_profile_new:
  *
- * Return value: a new GcmProfile object.
+ * Return value: a new #GcmProfile object.
+ *
+ * Since: 0.0.1
  **/
 GcmProfile *
 gcm_profile_new (void)
diff --git a/libcolor-glib/gcm-xserver.c b/libcolor-glib/gcm-xserver.c
index c8511ff..94642b6 100644
--- a/libcolor-glib/gcm-xserver.c
+++ b/libcolor-glib/gcm-xserver.c
@@ -76,9 +76,10 @@ G_DEFINE_TYPE (GcmXserver, gcm_xserver, G_TYPE_OBJECT)
  * @data: the data that is returned from the XServer. Free with g_free()
  * @length: the size of the returned data, or %NULL if you don't care
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Gets the ICC profile data from the XServer.
+ *
+ * Return value: %TRUE for success.
  **/
 gboolean
 gcm_xserver_get_root_window_profile_data (GcmXserver *xserver, guint8 **data, gsize *length, GError **error)
@@ -140,9 +141,12 @@ out:
  * @xserver: a valid %GcmXserver instance
  * @filename: the filename of the ICC profile
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Sets the ICC profile data to the XServer.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_set_root_window_profile (GcmXserver *xserver, const gchar *filename, GError **error)
@@ -176,9 +180,12 @@ out:
  * @data: the data that is to be set to the XServer
  * @length: the size of the data
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Sets the ICC profile data to the XServer.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_set_root_window_profile_data (GcmXserver *xserver, const guint8 *data, gsize length, GError **error)
@@ -224,9 +231,12 @@ out:
  * @major: the major version
  * @minor: the minor version
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Sets the ICC Profiles in X supported version to the XServer.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_set_protocol_version (GcmXserver *xserver, guint major, guint minor, GError **error)
@@ -270,9 +280,12 @@ out:
  * gcm_xserver_remove_protocol_version:
  * @xserver: a valid %GcmXserver instance
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Removes the ICC profile version data from the XServer.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_remove_protocol_version (GcmXserver *xserver, GError **error)
@@ -317,9 +330,12 @@ out:
  * @major: the major version
  * @minor: the minor version
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Gets the ICC profile data from the XServer.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_get_protocol_version (GcmXserver *xserver, guint *major, guint *minor, GError **error)
@@ -377,9 +393,12 @@ out:
  * gcm_xserver_remove_root_window_profile:
  * @xserver: a valid %GcmXserver instance
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Removes the ICC profile data from the XServer.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_remove_root_window_profile (GcmXserver *xserver, GError **error)
@@ -425,9 +444,12 @@ out:
  * @data: the data that is returned from the XServer. Free with g_free()
  * @length: the size of the returned data, or %NULL if you don't care
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Gets the ICC profile data from the specified output.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_get_output_profile_data (GcmXserver *xserver, const gchar *output_name, guint8 **data, gsize *length, GError **error)
@@ -509,9 +531,12 @@ out:
  * @output_name: the output name, e.g. "LVDS1"
  * @filename: the filename of the ICC profile
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Sets the ICC profile data to the specified output.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_set_output_profile (GcmXserver *xserver, const gchar *output_name, const gchar *filename, GError **error)
@@ -546,9 +571,12 @@ out:
  * @data: the data that is to be set to the XServer
  * @length: the size of the data
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Sets the ICC profile data to the specified output.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_set_output_profile_data (GcmXserver *xserver, const gchar *output_name, const guint8 *data, gsize length, GError **error)
@@ -602,9 +630,12 @@ out:
  * @xserver: a valid %GcmXserver instance
  * @output_name: the output name, e.g. "LVDS1"
  * @error: a %GError that is set in the result of an error, or %NULL
- * Return value: %TRUE for success.
  *
  * Sets the ICC profile data to the specified output.
+ *
+ * Return value: %TRUE for success.
+ *
+ * Since: 0.0.1
  **/
 gboolean
 gcm_xserver_remove_output_profile (GcmXserver *xserver, const gchar *output_name, GError **error)
@@ -747,6 +778,8 @@ gcm_xserver_finalize (GObject *object)
  * gcm_xserver_new:
  *
  * Return value: a new GcmXserver object.
+ *
+ * Since: 0.0.1
  **/
 GcmXserver *
 gcm_xserver_new (void)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]