GNOME.org
 

[cheese] Improve documentation to pass gtk-doc tests

commit 691a7308a8960f13b18d67160828e5c68c515f00
Author: David King <amigadave amigadave com>
Date:   Sun Oct 30 16:26:22 2011 +0100

    Improve documentation to pass gtk-doc tests
    
    Add the deprecated API index to the documentation. Complete the rename
    of cheese_camera_set_device_by_dev_file() to
    cheese_camera_set_device_by_device_node(). Add missing documentation to
    reach 100% symbol coverage.

 .gitignore                               |    1 +
 docs/reference/cheese-docs.xml           |    4 +++
 docs/reference/cheese-sections.txt       |    2 +-
 libcheese/cheese-camera-device-monitor.h |    2 +
 libcheese/cheese-camera-device.c         |   29 +++++++++++++++++++-----
 libcheese/cheese-camera.c                |   35 ++++++++++++++++++++++++-----
 libcheese/cheese-camera.h                |    4 ++-
 libcheese/cheese-effect.c                |   12 ++++++++-
 libcheese/cheese-fileutil.c              |    6 +++++
 libcheese/cheese-flash.c                 |    2 +
 src/cheese-preferences.vala              |    2 +-
 src/vapi/cheese-common.vapi              |    4 +-
 12 files changed, 84 insertions(+), 19 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 769ba56..1b6305b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,7 @@ Makefile.in*
 /po/*.mo
 /po/.intltool-merge-cache
 /po/POTFILES
+/po/cheese.pot
 /po/stamp-it
 /src/*.c
 /tests/cheese-test-widget
diff --git a/docs/reference/cheese-docs.xml b/docs/reference/cheese-docs.xml
index 4face42..de2d1fb 100644
--- a/docs/reference/cheese-docs.xml
+++ b/docs/reference/cheese-docs.xml
@@ -57,6 +57,10 @@
     <title>API Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
   </index>
+  <index id="api-index-deprecated" role="deprecated">
+    <title>Index of deprecated symbols</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
 
   <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/docs/reference/cheese-sections.txt b/docs/reference/cheese-sections.txt
index 780191d..15db465 100644
--- a/docs/reference/cheese-sections.txt
+++ b/docs/reference/cheese-sections.txt
@@ -28,7 +28,7 @@ cheese_camera_get_current_video_format
 cheese_camera_get_video_formats
 cheese_camera_set_video_format
 cheese_camera_get_selected_device
-cheese_camera_set_device_by_dev_file
+cheese_camera_set_device_by_device_node
 cheese_camera_set_effect
 cheese_camera_get_balance_property_range
 cheese_camera_set_balance_property
diff --git a/libcheese/cheese-camera-device-monitor.h b/libcheese/cheese-camera-device-monitor.h
index a309c82..75c8120 100644
--- a/libcheese/cheese-camera-device-monitor.h
+++ b/libcheese/cheese-camera-device-monitor.h
@@ -59,6 +59,8 @@ struct _CheeseCameraDeviceMonitor
  * CheeseCameraDeviceMonitorClass:
  * @added: invoked when a new video capture device is connected
  * @removed: invoked when a video capture device is removed
+ *
+ * Class for #CheeseCameraDeviceMonitor.
  */
 struct _CheeseCameraDeviceMonitorClass
 {
diff --git a/libcheese/cheese-camera-device.c b/libcheese/cheese-camera-device.c
index 1630530..f740400 100644
--- a/libcheese/cheese-camera-device.c
+++ b/libcheese/cheese-camera-device.c
@@ -618,8 +618,10 @@ cheese_camera_device_new (const gchar *device_id,
  * cheese_camera_device_get_format_list:
  * @device: a #CheeseCameraDevice
  *
- * Returns: (element-type Cheese.VideoFormat) (transfer container): List of
- * #CheeseVideoFormat that the device supports
+ * Get the list of #CheeseVideoFormat that the @device supports.
+ *
+ * Returns: (element-type Cheese.VideoFormat) (transfer container): list of
+ * #CheeseVideoFormat
  */
 GList *
 cheese_camera_device_get_format_list (CheeseCameraDevice *device)
@@ -631,6 +633,9 @@ cheese_camera_device_get_format_list (CheeseCameraDevice *device)
  * cheese_camera_device_get_name:
  * @device: a #CheeseCameraDevice
  *
+ * Get a human-readable name for the device, as reported by udev, which is
+ * suitable for display to a user.
+ *
  * Returns: (transfer none): the human-readable name of the video capture device
  */
 const gchar *
@@ -643,6 +648,8 @@ cheese_camera_device_get_name (CheeseCameraDevice *device)
  * cheese_camera_device_get_uuid:
  * @device: a #CheeseCameraDevice
  *
+ * Get the UUID of the @device, as reported by udev.
+ *
  * Returns: (transfer none): the UUID of the video capture device
  */
 const gchar *
@@ -655,7 +662,11 @@ cheese_camera_device_get_uuid (CheeseCameraDevice *device)
  * cheese_camera_device_get_src:
  * @device: a #CheeseCameraDevice
  *
- * Returns: (transfer none)
+ * Get the name of the source GStreamer element for the @device. Currently,
+ * this will be either v4lsrc or v4l2src, depending on the version of the
+ * Video4Linux API that the device supports.
+ *
+ * Returns: (transfer none): the name of the source GStreamer element
  */
 const gchar *
 cheese_camera_device_get_src (CheeseCameraDevice *device)
@@ -667,6 +678,8 @@ cheese_camera_device_get_src (CheeseCameraDevice *device)
  * cheese_camera_device_get_device_file:
  * @device: a #CheeseCameraDevice
  *
+ * Get the path to the device node associated with the @device.
+ *
  * Returns: (transfer none): the path to the device node of the video capture
  * device
  */
@@ -680,8 +693,10 @@ cheese_camera_device_get_device_file (CheeseCameraDevice *device)
  * cheese_camera_device_get_best_format:
  * @device: a #CheeseCameraDevice
  *
- * Returns: (transfer full): the highest-resolution #CheeseVideoFormat
- * supported be the @device
+ * Get the #CheeseVideoFormat with the highest rsolution for this @device.
+ *
+ * Returns: (transfer full): the highest-resolution supported
+ * #CheeseVideoFormat
  */
 
 CheeseVideoFormat *
@@ -699,7 +714,9 @@ cheese_camera_device_get_best_format (CheeseCameraDevice *device)
  * @device: a #CheeseCameraDevice
  * @format: a #CheeseVideoFormat
  *
- * Returns: (transfer full): the #GstCaps for the given @format on the @device
+ * Get the #GstCaps for the given @format on the @device.
+ *
+ * Returns: (transfer full): the #GstCaps for the given @format
  */
 GstCaps *
 cheese_camera_device_get_caps_for_format (CheeseCameraDevice *device,
diff --git a/libcheese/cheese-camera.c b/libcheese/cheese-camera.c
index ae1d2b7..bcb66a1 100644
--- a/libcheese/cheese-camera.c
+++ b/libcheese/cheese-camera.c
@@ -567,6 +567,9 @@ cheese_camera_create_video_filter_bin (CheeseCamera *camera, GError **error)
  * cheese_camera_get_num_camera_devices:
  * @camera: a #CheeseCamera
  *
+ * Get the number of #CheeseCameraDevice found on the system managed by
+ * @camera.
+ *
  * Returns: the number of #CheeseCameraDevice objects on the system
  */
 static int
@@ -581,6 +584,8 @@ cheese_camera_get_num_camera_devices (CheeseCamera *camera)
  * cheese_camera_get_selected_device:
  * @camera: a #CheeseCamera
  *
+ * Get the currently-selected #CheeseCameraDevice of the @camera.
+ *
  * Returns: (transfer none): a #CheeseCameraDevice, or %NULL if there is no
  * selected device
  */
@@ -596,11 +601,11 @@ cheese_camera_get_selected_device (CheeseCamera *camera)
     return NULL;
 }
 
-/*
- * cheese_camera_device_switch_camera_device:
+/**
+ * cheese_camera_switch_camera_device:
  * @camera: a #CheeseCamera
  *
- * Toggle the playing/recording state of the #CheeseCamera.
+ * Toggle the playing/recording state of the @camera.
  */
 void
 cheese_camera_switch_camera_device (CheeseCamera *camera)
@@ -813,6 +818,8 @@ cheese_camera_toggle_effects_pipeline (CheeseCamera *camera, gboolean active)
  * @camera: a #CheeseCamera
  * @effect: a #CheeseEffect
  * @texture: a #ClutterTexture
+ *
+ * Connect the supplied @texture to the @camera, using @effect.
  */
 void
 cheese_camera_connect_effect_texture (CheeseCamera *camera, CheeseEffect *effect, ClutterTexture *texture)
@@ -877,7 +884,9 @@ cheese_camera_start_video_recording (CheeseCamera *camera, const char *filename)
 
 /*
  * cheese_camera_force_stop_video_recording:
- * @data: a #CheeseCamera on which to forcibly stop video recording
+ * @data: a #CheeseCamera
+ *
+ * Forcible stop a #CheeseCamera from recording video.
  *
  * Returns: %FALSE
  */
@@ -1001,6 +1010,9 @@ cheese_camera_take_photo (CheeseCamera *camera, const char *filename)
  * cheese_camera_take_photo_pixbuf:
  * @camera: a #CheeseCamera
  *
+ * Take a photo with the @camera and emit it in the ::capture-start signal as a
+ * #GdkPixbuf.
+ *
  * Returns: %TRUE if the photo was successfully captured, %FALSE otherwise
  */
 gboolean
@@ -1247,6 +1259,8 @@ cheese_camera_init (CheeseCamera *camera)
  * @x_resolution: the resolution width
  * @y_resolution: the resolution height
  *
+ * Create a new #CheeseCamera object.
+ *
  * Returns: a new #CheeseCamera
  */
 CheeseCamera *
@@ -1277,13 +1291,13 @@ cheese_camera_new (ClutterTexture *video_texture, const gchar *camera_device_nam
 /**
  * cheese_camera_set_device_by_device_node:
  * @camera: a #CheeseCamera
- * @file: the device node path
+ * @file: (type filename): the device node path
  *
  * Set the active video capture device of the @camera, matching by device node
  * path.
  */
 void
-cheese_camera_set_device_by_dev_file (CheeseCamera *camera, const gchar *file)
+cheese_camera_set_device_by_device_node (CheeseCamera *camera, const gchar *file)
 {
   g_return_if_fail (CHEESE_IS_CAMERA (camera));
   g_object_set (camera, "device-name", file, NULL);
@@ -1453,6 +1467,8 @@ cheese_camera_get_video_formats (CheeseCamera *camera)
  * cheese_camera_is_playing:
  * @camera: a #CheeseCamera
  *
+ * Get whether the @camera is in the playing state.
+ *
  * Returns: %TRUE if the #CheeseCamera is in the playing state, %FALSE
  * otherwise
  */
@@ -1502,6 +1518,8 @@ cheese_camera_set_video_format (CheeseCamera *camera, CheeseVideoFormat *format)
  * cheese_camera_get_current_video_format:
  * @camera: a #CheeseCamera
  *
+ * Get the #CheeseVideoFormat that is currently set on the @camera.
+ *
  * Returns: (transfer none): the #CheeseVideoFormat set on the #CheeseCamera
  */
 const CheeseVideoFormat *
@@ -1522,6 +1540,9 @@ cheese_camera_get_current_video_format (CheeseCamera *camera)
  * @max: (out): maximum value
  * @def: (out): default value
  *
+ * Get the minimum, maximum and default values for the requested @property of
+ * the @camera.
+ *
  * Returns: %TRUE if the operation was successful, %FALSE otherwise
  */
 gboolean
@@ -1559,6 +1580,8 @@ cheese_camera_get_balance_property_range (CheeseCamera *camera,
  * @camera: A #CheeseCamera
  * @property: name of the balance property
  * @value: value to be set
+ *
+ * Set the requested @property on the @camera to @value.
  */
 void
 cheese_camera_set_balance_property (CheeseCamera *camera, const gchar *property, gdouble value)
diff --git a/libcheese/cheese-camera.h b/libcheese/cheese-camera.h
index eab3389..5b6f273 100644
--- a/libcheese/cheese-camera.h
+++ b/libcheese/cheese-camera.h
@@ -51,6 +51,8 @@ typedef struct _CheeseCamera CheeseCamera;
  * @video_saved: invoked when a video was saved to disk
  * @state_flags_changed: invoked when the state of the camera #GstElement
  * changed
+ *
+ * Class for #CheeseCamera.
  */
 struct _CheeseCameraClass
 {
@@ -113,7 +115,7 @@ gboolean            cheese_camera_take_photo (CheeseCamera *camera, const gchar
 gboolean            cheese_camera_take_photo_pixbuf (CheeseCamera *camera);
 CheeseCameraDevice *cheese_camera_get_selected_device (CheeseCamera *camera);
 GPtrArray *         cheese_camera_get_camera_devices (CheeseCamera *camera);
-void                cheese_camera_set_device_by_dev_file (CheeseCamera *camera, const gchar *file);
+void                cheese_camera_set_device_by_device_node (CheeseCamera *camera, const gchar *file);
 void                cheese_camera_switch_camera_device (CheeseCamera *camera);
 GList *             cheese_camera_get_video_formats (CheeseCamera *camera);
 void                cheese_camera_set_video_format (CheeseCamera      *camera,
diff --git a/libcheese/cheese-effect.c b/libcheese/cheese-effect.c
index 889548a..e22382d 100644
--- a/libcheese/cheese-effect.c
+++ b/libcheese/cheese-effect.c
@@ -147,10 +147,18 @@ cheese_effect_class_init (CheeseEffectClass *klass)
                                                         G_PARAM_READWRITE));
 }
 
+/**
+ * cheese_effect_is_preview_connected:
+ * @effect: a #CheeseEffect
+ *
+ * Get whether the @effect is connected to a video stream, for previews.
+ *
+ * Returns: %TRUE if the preview is connected, %FALSE otherwise.
+ */
 gboolean
-cheese_effect_is_preview_connected (CheeseEffect *self)
+cheese_effect_is_preview_connected (CheeseEffect *effect)
 {
-  return self->priv->control_valve != NULL;
+  return effect->priv->control_valve != NULL;
 }
 
 /**
diff --git a/libcheese/cheese-fileutil.c b/libcheese/cheese-fileutil.c
index cf44592..d73a563 100644
--- a/libcheese/cheese-fileutil.c
+++ b/libcheese/cheese-fileutil.c
@@ -59,6 +59,8 @@ cheese_fileutil_get_path_before_224 (CheeseFileUtil *fileutil);
  * cheese_fileutil_get_video_path:
  * @fileutil: a #CheeseFileUtil
  *
+ * Get the path where Cheese video files are stored.
+ *
  * Returns: (transfer none) (type filename): the Cheese video path
  */
 const gchar *
@@ -71,6 +73,8 @@ cheese_fileutil_get_video_path (CheeseFileUtil *fileutil)
  * cheese_fileutil_get_photo_path:
  * @fileutil: a #CheeseFileUtil
  *
+ * Get the path where Cheese photo files are stored.
+ *
  * Returns: (transfer none) (type filename): the Cheese photo path
  */
 const gchar *
@@ -254,6 +258,8 @@ cheese_fileutil_init (CheeseFileUtil *fileutil)
 /**
  * cheese_fileutil_new:
  *
+ * Create a new #CheeseFileUtil object.
+ *
  * Returns: a new #CheeseFileUtil
  */
 CheeseFileUtil *
diff --git a/libcheese/cheese-flash.c b/libcheese/cheese-flash.c
index 2ccc535..3c50936 100644
--- a/libcheese/cheese-flash.c
+++ b/libcheese/cheese-flash.c
@@ -381,6 +381,8 @@ cheese_flash_fire (CheeseFlash *flash)
  * cheese_flash_new:
  * @parent: a parent #GtkWidget
  *
+ * Create a new #CheeseFlash, associated with the @parent widget.
+ *
  * Returns: a new #CheeseFlash
  */
 CheeseFlash *
diff --git a/src/cheese-preferences.vala b/src/cheese-preferences.vala
index 3c18f41..2a8e873 100644
--- a/src/cheese-preferences.vala
+++ b/src/cheese-preferences.vala
@@ -215,7 +215,7 @@ public class Cheese.PreferencesDialog : GLib.Object
 
     combo.get_active_iter (out iter);
     combo.model.get (iter, 1, out dev);
-    camera.set_device_by_dev_file (dev.get_device_file ());
+    camera.set_device_by_device_node (dev.get_device_file ());
     camera.switch_camera_device ();
     setup_resolutions_for_device (camera.get_selected_device ());
     settings.set_string ("camera", dev.get_device_file ());
diff --git a/src/vapi/cheese-common.vapi b/src/vapi/cheese-common.vapi
index a65f3d2..beb391c 100644
--- a/src/vapi/cheese-common.vapi
+++ b/src/vapi/cheese-common.vapi
@@ -37,8 +37,8 @@ namespace Cheese
     public bool                        has_camera ();
     public void                        play ();
     public void                        set_balance_property (string property, double value);
-    public void                        set_device_by_dev_file (string file);
-    public void                        set_device_by_dev_udi (string udi);
+    public void                        set_device_by_device_node (string file);
+    public void                        set_device_by_uuid (string uuid);
     public void                        set_effect (Cheese.Effect effect);
     public void                        toggle_effects_pipeline (bool active);
     public void                        connect_effect_texture (Cheese.Effect effect, Clutter.Texture texture);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]