GstDevice: Document GstDevice and related classes

docs/gst/gstreamer-sections.txt

@@ -1580,6 +1580,10 @@ gst_message_parse_context_type
 gst_message_new_have_context
 gst_message_parse_have_context
 
+gst_message_new_device_added
+gst_message_new_device_removed
+gst_message_parse_device_added
+gst_message_parse_device_removed
 <SUBSECTION Standard>
 GstMessageClass
 GST_MESSAGE
@@ -3324,6 +3328,15 @@ GST_CHECK_VERSION
 GstDevice
 GstDeviceClass
 
+gst_device_create_element
+gst_device_get_caps
+gst_device_get_display_name
+gst_device_get_klass
+gst_device_has_classes
+gst_device_has_classesv
+gst_device_reconfigure_element
+
+<SUBSECTION Standard>
 GST_DEVICE
 GST_DEVICE_CAST
 GST_DEVICE_CLASS
@@ -3331,15 +3344,7 @@ GST_DEVICE_GET_CLASS
 GST_IS_DEVICE
 GST_IS_DEVICE_CLASS
 GST_TYPE_DEVICE
-
-gst_device_create_element
-gst_device_get_caps
-gst_device_get_display_name
-gst_device_get_klass
 gst_device_get_type
-gst_device_has_classes
-gst_device_has_classesv
-gst_device_reconfigure_element
 </SECTION>
 
 <SECTION>
@@ -3347,13 +3352,6 @@ gst_device_reconfigure_element
 <TITLE>GstDeviceMonitor</TITLE>
 GstDeviceMonitor
 GstDeviceMonitorClass
-GST_DEVICE_MONITOR
-GST_DEVICE_MONITOR_CAST
-GST_DEVICE_MONITOR_CLASS
-GST_DEVICE_MONITOR_GET_CLASS
-GST_IS_DEVICE_MONITOR
-GST_IS_DEVICE_MONITOR_CLASS
-GST_TYPE_DEVICE_MONITOR
 gst_device_monitor_can_monitor
 gst_device_monitor_class_add_metadata
 gst_device_monitor_class_add_static_metadata
@@ -3365,10 +3363,20 @@ gst_device_monitor_device_remove
 gst_device_monitor_get_bus
 gst_device_monitor_get_devices
 gst_device_monitor_get_factory
-gst_device_monitor_get_type
 gst_device_monitor_register
 gst_device_monitor_start
 gst_device_monitor_stop
+
+<SUBSECTION Standard>
+GstDevicePrivate
+GST_DEVICE_MONITOR
+GST_DEVICE_MONITOR_CAST
+GST_DEVICE_MONITOR_CLASS
+GST_DEVICE_MONITOR_GET_CLASS
+GST_IS_DEVICE_MONITOR
+GST_IS_DEVICE_MONITOR_CLASS
+GST_TYPE_DEVICE_MONITOR
+gst_device_monitor_get_type
 </SECTION>
 
 <SECTION>
@@ -3376,20 +3384,25 @@ gst_device_monitor_stop
 <TITLE>GstDeviceMonitorFactory</TITLE>
 GstDeviceMonitorFactory
 GstDeviceMonitorFactoryClass
-GST_DEVICE_MONITOR_FACTORY
-GST_DEVICE_MONITOR_FACTORY_CAST
-GST_DEVICE_MONITOR_FACTORY_CLASS
-GST_TYPE_DEVICE_MONITOR_FACTORY
 gst_device_monitor_factory_find
 gst_device_monitor_factory_get
 gst_device_monitor_factory_get_by_name
 gst_device_monitor_factory_get_device_monitor_type
 gst_device_monitor_factory_get_metadata
 gst_device_monitor_factory_get_metadata_keys
-gst_device_monitor_factory_get_type
 gst_device_monitor_factory_has_classes
 gst_device_monitor_factory_has_classesv
 gst_device_monitor_factory_list_get_device_monitors
+
+<SUBSECTION Standard>
+GstDeviceMonitorPrivate
+GST_DEVICE_MONITOR_FACTORY
+GST_DEVICE_MONITOR_FACTORY_CAST
+GST_DEVICE_MONITOR_FACTORY_CLASS
+GST_TYPE_DEVICE_MONITOR_FACTORY
+GST_IS_DEVICE_MONITOR_FACTORY
+GST_IS_DEVICE_MONITOR_FACTORY_CLASS
+gst_device_monitor_factory_get_type
 </SECTION>
 
 <SECTION>
@@ -3397,6 +3410,18 @@ gst_device_monitor_factory_list_get_device_monitors
 <TITLE>GstGlobalDeviceMonitor</TITLE>
 GstGlobalDeviceMonitor
 GstGlobalDeviceMonitorClass
+gst_global_device_monitor_get_bus
+gst_global_device_monitor_get_caps_filter
+gst_global_device_monitor_get_classes_filter
+gst_global_device_monitor_get_devices
+gst_global_device_monitor_new
+gst_global_device_monitor_set_caps_filter
+gst_global_device_monitor_set_classes_filter
+gst_global_device_monitor_start
+gst_global_device_monitor_stop
+
+<SUBSECTION Standard>
+GstGlobalDeviceMonitorPrivate
 GST_GLOBAL_DEVICE_MONITOR
 GST_GLOBAL_DEVICE_MONITOR_CAST
 GST_GLOBAL_DEVICE_MONITOR_CLASS
@@ -3404,15 +3429,6 @@ GST_GLOBAL_DEVICE_MONITOR_GET_CLASS
 GST_IS_GLOBAL_DEVICE_MONITOR
 GST_IS_GLOBAL_DEVICE_MONITOR_CLASS
 GST_TYPE_GLOBAL_DEVICE_MONITOR
-gst_global_device_monitor_get_bus
-gst_global_device_monitor_get_caps_filter
-gst_global_device_monitor_get_classes_filter
-gst_global_device_monitor_get_devices
 gst_global_device_monitor_get_type
-gst_global_device_monitor_new
-gst_global_device_monitor_set_caps_filter
-gst_global_device_monitor_set_classes_filter
-gst_global_device_monitor_start
-gst_global_device_monitor_stop
 </SECTION>
 

gst/gstdevice.c

@@ -19,6 +19,21 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstdevice
+ * @short_description: Object representing a device
+ * @see_also: #GstDeviceMonitor
+ *
+ * #GstDevice are objects representing a device, they contain
+ * relevant metadata about the device, such as its class and the #GstCaps
+ * representing the media types it can produce or handle.
+ *
+ * #GstDevice are created by #GstDeviceMonitor objects which can be
+ * aggregated by #GstGlobalDeviceMonitor objects.
+ *
+ * Since: 1.4
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -163,6 +178,9 @@ gst_device_set_property (GObject * object, guint prop_id,
  * @name: (allow-none): name of new element, or %NULL to automatically
  * create a unique name.
  *
+ * Creates the element with all of the required paramaters set to use
+ * this device.
+ *
  * Returns: (transfer full): a new #GstElement configured to use this device
  *
  * Since: 1.4

gst/gstdevice.h

@@ -42,6 +42,14 @@ typedef struct _GstDevicePrivate GstDevicePrivate;
 #define GST_DEVICE_CLASS(klass)         (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_DEVICE, GstDeviceClass))
 #define GST_DEVICE_CAST(obj)            ((GstDevice *)(obj))
 
+/**
+ * GstDevice:
+ * @parent: The parent #GstObject strucuture.
+ *
+ * A device object.
+ *
+ * Since: 1.4
+ */
 
 struct _GstDevice {
   GstObject         parent;
@@ -52,6 +60,20 @@ struct _GstDevice {
   gpointer _gst_reserved[GST_PADDING];
 };
 
+/**
+ * GstDeviceClass:
+ * @parent_class: The parent #GstObjectClass strucuture.
+ * @create_element: Creates the fully configured element to access this device.
+ *  Subclasses need to override this and return a new element.
+ * @reconfigure_element: This only needs to be implemented by subclasses if the
+ *  element can be reconfigured to use a different device. See the documentation
+ *  for gst_device_reconfigure_element().
+ *
+ * The class structure for a #GstDevice object.
+ *
+ * Since: 1.4
+ */
+
 struct _GstDeviceClass {
   GstObjectClass    parent_class;
 

gst/gstdevicemonitor.c

@@ -19,6 +19,24 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstdevicemonitor
+ * @short_description: A device monitor and prober
+ * @see_also: #GstDevice, #GstGlobalDeviceMonitor
+ *
+ * A #GstDeviceMonitor subclass is provided by a plugin that handles devices
+ * if there is a way to programatically list connected devices. It can also
+ * optionally provide updates to the list of connected devices.
+ *
+ * Each #GstDeviceMonitor subclass is a singleton, a plugin should
+ * normally provide a single subclass for all devices.
+ *
+ * Applications would normally use a #GstGlobalDeviceMonitor to monitor devices
+ * from all revelant monitors.
+ *
+ * Since: 1.4
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

gst/gstdevicemonitor.h

@@ -44,17 +44,21 @@ typedef struct _GstDeviceMonitorPrivate GstDeviceMonitorPrivate;
 
 /**
  * GstDeviceMonitor:
+ * @parent: The parent #GstObject
+ * @devices: a #GList of the #GstDevice objects
+ *
+ * The structure of the base #GstDeviceMonitor
  *
  * Since: 1.4
  */
 struct _GstDeviceMonitor {
   GstObject         parent;
 
-  /*< private >*/
-
   /* Protected by the Object lock */
   GList *devices;
 
+  /*< private >*/
+
   GstDeviceMonitorPrivate *priv;
 
   gpointer _gst_reserved[GST_PADDING];
@@ -62,12 +66,15 @@ struct _GstDeviceMonitor {
 
 /**
  * GstDeviceMonitorClass:
+ * @parent_class: the parent #GstObjectClass structure
  * @factory: a pointer to the #GstDeviceMonitorFactory that creates this
  *  monitor
  * @probe: Returns a list of devices that are currently available.
  *  This should never block.
- * @start: Starts monitoring for new devices.
+ * @start: Starts monitoring for new devices. Only subclasses that can know
- * @stop: Stops monitoring for new devices
+ *  that devices have been added or remove need to implement this method.
+ * @stop: Stops monitoring for new devices. Only subclasses that implement
+ *  the start() method need to implement this method.
  *
  * The structure of the base #GstDeviceMonitorClass
  *

gst/gstdevicemonitorfactory.h

@@ -33,6 +33,14 @@
  *
  * Since: 1.4
  */
+
+/**
+ * GstDeviceMonitorFactoryClass:
+ *
+ * The opaque #GstDeviceMonitorFactoryClass data structure.
+ *
+ * Since: 1.4
+ */
 typedef struct _GstDeviceMonitorFactory GstDeviceMonitorFactory;
 typedef struct _GstDeviceMonitorFactoryClass GstDeviceMonitorFactoryClass;
 

gst/gstglobaldevicemonitor.c

@@ -18,7 +18,23 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
-/* FIXME: documentation section! */
+
+/**
+ * SECTION:gstglobaldevicemonitor
+ * @short_description: A global device monitor and prober
+ * @see_also: #GstDevice, #GstDeviceMonitor
+ *
+ * Applications should create a #GstGlobalDeviceMonitor when they want
+ * to probe, list and monitor devices of a specific type. The
+ * #GstGlobalDeviceMonitor will create the appropriate
+ * #GstDeviceMonitor objects and manage them. It will then post
+ * messages on its #GstBus for devices that have been added and
+ * removed.
+ *
+ * Since: 1.4
+ */
+
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -230,8 +246,8 @@ again:
  * @monitor: A #GstGlobalDeviceMonitor
  *
  * Starts monitoring the devices, one this has succeeded, the
- * #GstGlobalDeviceMonitor:added and #GstGlobalDeviceMonitor:removed
+ * %GST_MESSAGE_DEVICE_ADDED and %GST_MESSAGE_DEVICE_REMOVED messages
- * signals will be emitted when the list of devices changes.
+ * will be emitted on the bus when the list of devices changes.
  *
  * Returns: %TRUE if the device monitoring could be started
  *
@@ -301,7 +317,7 @@ gst_global_device_monitor_stop (GstGlobalDeviceMonitor * monitor)
 
 /**
  * gst_global_device_monitor_set_classes_filter:
- * @self: the global device monitor
+ * @monitor: the global device monitor
  * @classes: device classes to use as filter
  *
  * Filter devices monitored by device class, e.g. in case you are only
@@ -431,6 +447,8 @@ gst_global_device_monitor_set_caps_filter (GstGlobalDeviceMonitor * monitor,
  * gst_global_device_monitor_get_caps_filter:
  * @monitor: a global device monitor
  *
+ * Get the #GstCaps filter set by gst_global_device_monitor_set_caps_filter().
+ *
  * Returns: (transfer full): the filter caps that are active (or ANY caps)
  *
  * Since: 1.4
@@ -452,6 +470,8 @@ gst_global_device_monitor_get_caps_filter (GstGlobalDeviceMonitor * monitor)
 /**
  * gst_global_device_monitor_new:
  *
+ * Create a new #GstGlobalDeviceMonitor
+ *
  * Returns: (transfer full): a new global device monitor.
  *
  * Since: 1.4

gst/gstglobaldevicemonitor.h

@@ -44,6 +44,7 @@ typedef struct _GstGlobalDeviceMonitorClass GstGlobalDeviceMonitorClass;
 
 /**
  * GstGlobalDeviceMonitor:
+ * @parent: the parent #GstObject structure
  *
  * Opaque global device monitor object structure.
  *
@@ -61,6 +62,7 @@ struct _GstGlobalDeviceMonitor {
 
 /**
  * GstGlobalDeviceMonitorClass:
+ * @parent_class: the parent #GstObjectClass structure
  *
  * Opaque global device monitor class structure.
  *

gst/gstmessage.c

@@ -2361,6 +2361,7 @@ gst_message_new_device_added (GstObject * src, GstDevice * device)
 
 /**
  * gst_message_parse_device_added:
+ * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED
  * @device: (out) (allow-none) (transfer none): A location where to store a
  *  pointer to the new #GstDevice, or %NULL
  * 
@@ -2412,6 +2413,7 @@ gst_message_new_device_removed (GstObject * src, GstDevice * device)
 
 /**
  * gst_message_parse_device_removed:
+ * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_REMOVED
  * @device: (out) (allow-none) (transfer none): A location where to store a
  *  pointer to the removed #GstDevice, or %NULL
  *