[cheese] monitor: complete api docs

[Filippo Argiolas <fargiolas src gnome org>]

commit 0d67d273ec13bff068880dae45b652361a061229
Author: Filippo Argiolas <filippo argiolas gmail com>
Date:   Sun Feb 28 09:53:53 2010 +0100

    monitor: complete api docs

 docs/reference/Makefile.am               |    4 +++-
 libcheese/cheese-camera-device-monitor.c |   24 ++++++++++++++++++++++--
 libcheese/cheese-camera-device-monitor.h |   14 +++++++++-----
 3 files changed, 34 insertions(+), 8 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 49b8f49..541d39e 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -80,7 +80,9 @@ expand_content_files=
 # e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
 # e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
 INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(CHEESE_CFLAGS)
-GTKDOC_LIBS=$(top_builddir)/libcheese/libcheese-gtk.la
+GTKDOC_LIBS=\
+	$(top_builddir)/libcheese/libcheesecommon.la \
+	$(top_builddir)/libcheese/libcheese-gtk.la
 
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
 include $(top_srcdir)/gtk-doc.make
diff --git a/libcheese/cheese-camera-device-monitor.c b/libcheese/cheese-camera-device-monitor.c
index dd141eb..4b51438 100644
--- a/libcheese/cheese-camera-device-monitor.c
+++ b/libcheese/cheese-camera-device-monitor.c
@@ -2,7 +2,7 @@
  * Copyright © 2007,2008 Jaap Haitsma <jaap haitsma org>
  * Copyright © 2007-2009 daniel g. siegel <dgsiegel gnome org>
  * Copyright © 2008 Ryan Zeigler <zeiglerr gmail com>
- * Copyright © 2009 Filippo Argiolas <filippo argiolas gmail com>
+ * Copyright © 2010 Filippo Argiolas <filippo argiolas gmail com>
  *
  * Licensed under the GNU General Public License Version 2
  *
@@ -46,6 +46,21 @@
 #include "cheese-camera-device-monitor.h"
 #include "cheese-marshal.h"
 
+/**
+ * SECTION:cheese-camera-device-monitor
+ * @short_description: Simple object to enumerate v4l devices
+ * @include: cheese/cheese-camera-device-monitor.h
+ *
+ * #CheeseCameraDeviceMonitor provides a basic interface for
+ * video4linux device enumeration and hotplugging.
+ *
+ * It uses either GUdev or some platform specific code to list video
+ * devices.  It is also capable (right now in linux only, with the
+ * udev backend) to monitor device plugging and emit a
+ * CheeseCameraDeviceMonitor::added or
+ * CheeseCameraDeviceMonitor::removed signal when an event happens.
+ */
+
 G_DEFINE_TYPE (CheeseCameraDeviceMonitor, cheese_camera_device_monitor, G_TYPE_OBJECT)
 
 #define CHEESE_CAMERA_DEVICE_MONITOR_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o),                               \
@@ -334,6 +349,10 @@ cheese_camera_device_monitor_class_init (CheeseCameraDeviceMonitorClass *klass)
   /**
    * CheeseCameraDeviceMonitor::added:
    * @device: A private object representing the newly added camera.
+   * @id: Device unique identifier.
+   * @device: Device file name  (e.g. /dev/video2).
+   * @product_name: Device product name (human readable, intended to be displayed in a UI).
+   * @api_version: Supported video4linux API: 1 for v4l, 2 for v4l2.
    *
    * The ::added signal is emitted when a camera is added, or on start-up
    * after #cheese_camera_device_monitor_colplug is called.
@@ -347,7 +366,8 @@ cheese_camera_device_monitor_class_init (CheeseCameraDeviceMonitorClass *klass)
 
   /**
    * CheeseCameraDeviceMonitor::removed:
-   * @id: an ID representing the removed camera.
+   * @device: A private object representing the newly added camera
+   * @id: Device unique identifier.
    *
    * The ::removed signal is emitted when a camera is un-plugged, or
    * disabled on the system.
diff --git a/libcheese/cheese-camera-device-monitor.h b/libcheese/cheese-camera-device-monitor.h
index 3910054..fb59cb6 100644
--- a/libcheese/cheese-camera-device-monitor.h
+++ b/libcheese/cheese-camera-device-monitor.h
@@ -38,12 +38,16 @@ G_BEGIN_DECLS
 #define CHEESE_IS_CAMERA_DEVICE_MONITOR_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), CHEESE_TYPE_CAMERA_DEVICE_MONITOR))
 #define CHEESE_CAMERA_DEVICE_MONITOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), CHEESE_TYPE_CAMERA_DEVICE_MONITOR, \
                                                                               CheeseCameraDeviceMonitorClass))
-typedef struct
+
+typedef struct _CheeseCameraDeviceMonitorClass CheeseCameraDeviceMonitorClass;
+typedef struct _CheeseCameraDeviceMonitor CheeseCameraDeviceMonitor;
+
+struct _CheeseCameraDeviceMonitor
 {
   GObject parent;
-} CheeseCameraDeviceMonitor;
+};
 
-typedef struct
+struct _CheeseCameraDeviceMonitorClass
 {
   GObjectClass parent_class;
 
@@ -53,9 +57,9 @@ typedef struct
                 const char *product_name,
                 int api_version);
   void (*removed)(CheeseCameraDeviceMonitor *camera, const char *id);
-} CheeseCameraDeviceMonitorClass;
+};
 
-GType                      cheese_camera_device_monitor_get_type (void);
+GType                      cheese_camera_device_monitor_get_type (void) G_GNUC_CONST;
 CheeseCameraDeviceMonitor *cheese_camera_device_monitor_new (void);
 void                       cheese_camera_device_monitor_coldplug (CheeseCameraDeviceMonitor *monitor);