[cheese] Overhaul the libcheese documentation
- From: David King <davidk src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [cheese] Overhaul the libcheese documentation
- Date: Thu, 27 Oct 2011 21:45:22 +0000 (UTC)
commit c197715d77184b07f86a14ef3584a20a54e223e4
Author: David King <amigadave amigadave com>
Date: Thu Oct 27 23:38:50 2011 +0200
Overhaul the libcheese documentation
Add documentation for CheeseCameraDevice. Remove bogus XML included in
the library overview. Add section documentation to all classes, and mark
them as unstable. Add GObject and GObjectClass struct documentation.
docs/reference/Makefile.am | 1 -
docs/reference/cheese-docs.xml | 7 ++-
docs/reference/cheese-sections.txt | 19 +++++++
docs/reference/cheese.types | 2 +
libcheese/cheese-avatar-chooser.c | 10 ++++
libcheese/cheese-camera-device-monitor.c | 8 ++--
libcheese/cheese-camera-device-monitor.h | 13 +++++
libcheese/cheese-camera-device.c | 76 +++++++++++++++++++++++++----
libcheese/cheese-camera-device.h | 27 ++++++++--
libcheese/cheese-effect.c | 62 ++++++++++++++++++++++--
libcheese/cheese-effect.h | 33 +++++++++----
libcheese/cheese-widget.c | 10 ++++
libcheese/cheese-widget.h | 12 +++++
13 files changed, 240 insertions(+), 40 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index d03c282..26b933d 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -51,7 +51,6 @@ CFILE_GLOB=$(top_srcdir)/libcheese/*.c
# Header files to ignore when scanning.
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES= \
- cheese-camera-device.h \
cheese-camera.h \
cheese-aspect-frame.h \
cheese-fileutil.h \
diff --git a/docs/reference/cheese-docs.xml b/docs/reference/cheese-docs.xml
index 696d72f..a397603 100644
--- a/docs/reference/cheese-docs.xml
+++ b/docs/reference/cheese-docs.xml
@@ -11,29 +11,30 @@
<releaseinfo>
for cheese &version;.
The latest version of this documentation can be found on-line at
- <ulink role="online-location" url="http://library.gnome.org/devel/cheese/unstable/";>http://library.gnome.org/devel/cheese/unstable/</ulink>.
+ <ulink role="online-location" url="http://developer.gnome.org/cheese/unstable/";>http://developer.gnome.org/cheese/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<chapter>
<title>Cheese Overview</title>
- <partintro>
<para>
Cheese uses your webcam to take photos and videos, applies fancy special
effects and lets you share the fun with others
</para>
- </partintro>
<xi:include href="xml/cheese-widget.xml"/>
<xi:include href="xml/cheese-effect.xml"/>
+ <xi:include href="xml/cheese-camera-device.xml"/>
<xi:include href="xml/cheese-camera-device-monitor.xml"/>
<xi:include href="xml/cheese-avatar-chooser.xml"/>
</chapter>
+
<chapter id="object-tree">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
+
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
diff --git a/docs/reference/cheese-sections.txt b/docs/reference/cheese-sections.txt
index 11153da..18fc322 100644
--- a/docs/reference/cheese-sections.txt
+++ b/docs/reference/cheese-sections.txt
@@ -35,6 +35,25 @@ CHEESE_EFFECT_GET_CLASS
</SECTION>
<SECTION>
+<FILE>cheese-camera-device</FILE>
+<TITLE>CheeseCameraDevice</TITLE>
+CheeseCameraDevice
+CheeseCameraDeviceClass
+cheese_camera_device_new
+cheese_camera_device_get_name
+cheese_camera_device_get_id
+cheese_camera_device_get_device_file
+<SUBSECTION Standard>
+CHEESE_CAMERA_DEVICE
+CHEESE_IS_CAMERA_DEVICE
+CHEESE_TYPE_CAMERA_DEVICE
+cheese_camera_device_get_type
+CHEESE_CAMERA_DEVICE_CLASS
+CHEESE_IS_CAMERA_DEVICE_CLASS
+CHEESE_CAMERA_DEVICE_GET_CLASS
+</SECTION>
+
+<SECTION>
<FILE>cheese-camera-device-monitor</FILE>
<TITLE>CheeseCameraDeviceMonitor</TITLE>
CheeseCameraDeviceMonitorClass
diff --git a/docs/reference/cheese.types b/docs/reference/cheese.types
index ab80c99..f1800cb 100644
--- a/docs/reference/cheese.types
+++ b/docs/reference/cheese.types
@@ -1,4 +1,6 @@
cheese_avatar_chooser_get_type
+cheese_camera_device_get_type
cheese_camera_device_monitor_get_type
cheese_effect_get_type
+cheese_video_format_get_type
cheese_widget_get_type
diff --git a/libcheese/cheese-avatar-chooser.c b/libcheese/cheese-avatar-chooser.c
index 1b64e1e..71a6877 100644
--- a/libcheese/cheese-avatar-chooser.c
+++ b/libcheese/cheese-avatar-chooser.c
@@ -28,6 +28,16 @@
#include "cheese-avatar-chooser.h"
#include "um-crop-area.h"
+/**
+ * SECTION:cheese-avatar-chooser
+ * @short_description: A photo capture dialog for avatars
+ * @stability: Unstable
+ * @include: cheese/cheese-avatar-chooser.h
+ *
+ * #CheeseAvatarChooser presents a simple window to the user for taking a photo
+ * for use as an avatar.
+ */
+
enum
{
LAST_SIGNAL
diff --git a/libcheese/cheese-camera-device-monitor.c b/libcheese/cheese-camera-device-monitor.c
index 7b02be0..39f3b8a 100644
--- a/libcheese/cheese-camera-device-monitor.c
+++ b/libcheese/cheese-camera-device-monitor.c
@@ -48,15 +48,15 @@
/**
* SECTION:cheese-camera-device-monitor
* @short_description: Simple object to enumerate v4l devices
+ * @stability: Unstable
* @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
+ * 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.
*/
diff --git a/libcheese/cheese-camera-device-monitor.h b/libcheese/cheese-camera-device-monitor.h
index d0d98a4..0a5f3be 100644
--- a/libcheese/cheese-camera-device-monitor.h
+++ b/libcheese/cheese-camera-device-monitor.h
@@ -41,15 +41,28 @@ G_BEGIN_DECLS
typedef struct _CheeseCameraDeviceMonitorClass CheeseCameraDeviceMonitorClass;
typedef struct _CheeseCameraDeviceMonitor CheeseCameraDeviceMonitor;
+/**
+ * CheeseCameraDeviceMonitor:
+ *
+ * Use the accessor functions below.
+ */
struct _CheeseCameraDeviceMonitor
{
+ /*< private >*/
GObject parent;
};
+/**
+ * CheeseCameraDeviceMonitorClass:
+ * @added: invoked when a new video capture device is connected
+ * @removed: invoked when a video capture device is removed
+ */
struct _CheeseCameraDeviceMonitorClass
{
+ /*< private >*/
GObjectClass parent_class;
+ /*< public >*/
void (*added)(CheeseCameraDeviceMonitor *camera,
const char *id,
const char *device_file,
diff --git a/libcheese/cheese-camera-device.c b/libcheese/cheese-camera-device.c
index 7503c6d..1b83d77 100644
--- a/libcheese/cheese-camera-device.c
+++ b/libcheese/cheese-camera-device.c
@@ -30,6 +30,15 @@
#include "cheese-camera-device.h"
+/**
+ * SECTION:cheese-camera-device
+ * @short_description: Object to represent a video capture device
+ * @stability: Unstable
+ * @include: cheese/cheese-camera-device.h
+ *
+ * #CheeseCameraDevice provides an abstraction of a video capture device.
+ */
+
static void cheese_camera_device_initable_iface_init (GInitableIface *iface);
static gboolean cheese_camera_device_initable_init (GInitable *initable,
GCancellable *cancellable,
@@ -476,25 +485,47 @@ cheese_camera_device_class_init (CheeseCameraDeviceClass *klass)
object_class->set_property = cheese_camera_device_set_property;
object_class->constructed = cheese_camera_device_constructed;
+ /**
+ * CheeseCameraDevice:name:
+ *
+ * Human-readable name of the video capture device, for display to the user.
+ */
g_object_class_install_property (object_class, PROP_NAME,
g_param_spec_string ("name",
NULL, NULL, NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+ /**
+ * CheeseCameraDevice:device-file:
+ *
+ * Path to the device node of the video capture device.
+ */
g_object_class_install_property (object_class, PROP_FILE,
g_param_spec_string ("device-file",
NULL, NULL, NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+ /**
+ * CheeseCameraDevice:device-id:
+ *
+ * UUID of the video capture device.
+ */
g_object_class_install_property (object_class, PROP_ID,
g_param_spec_string ("device-id",
NULL, NULL, NULL,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+ /**
+ * CheeseCameraDevice:api:
+ *
+ * Version of the Video4Linux API that the device supports. Currently, either
+ * 1 or 2 are supported.
+ */
g_object_class_install_property (object_class, PROP_API,
g_param_spec_int ("api", NULL, NULL,
1, 2, 2,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+
g_type_class_add_private (klass, sizeof (CheeseCameraDevicePrivate));
}
@@ -551,6 +582,23 @@ cheese_camera_device_initable_init (GInitable *initable,
return TRUE;
}
+/* public methods */
+
+/**
+ * cheese_camera_device_new:
+ * @device_id: UUID of the device, as supplied by udev
+ * @device_file: path to the device node of the video capture device
+ * @product_name: human-readable name of the device, as supplied by udev
+ * @api_version: version of the Video4Linux API that the device uses. Currently
+ * either 1 or 2
+ * @error: a location to store errors
+ *
+ * Tries to create a new #CheeseCameraDevice with the supplied parameters. If
+ * construction fails, %NULL is returned, and @error is set.
+ *
+ * Returns: a new #CheeseCameraDevice, or %NULL
+ */
+
CheeseCameraDevice *
cheese_camera_device_new (const gchar *device_id,
const gchar *device_file,
@@ -567,13 +615,12 @@ cheese_camera_device_new (const gchar *device_id,
NULL));
}
-/* public methods */
-
/**
* cheese_camera_device_get_format_list:
* @device: a #CheeseCameraDevice
*
- * Returns: (element-type Cheese.VideoFormat) (transfer container): List of #CheeseVideoFormat
+ * Returns: (element-type Cheese.VideoFormat) (transfer container): List of
+ * #CheeseVideoFormat
*/
GList *
@@ -589,7 +636,7 @@ cheese_camera_device_get_format_list (CheeseCameraDevice *device)
* cheese_camera_device_get_name:
* @device: a #CheeseCameraDevice
*
- * Returns: (transfer none)
+ * Returns: (transfer none): the human-readable name of the video capture device
*/
const gchar *
@@ -601,10 +648,11 @@ cheese_camera_device_get_name (CheeseCameraDevice *device)
return priv->name;
}
-/** cheese_camera_device_get_id:
+/**
+ * cheese_camera_device_get_id:
* @device: a #CheeseCameraDevice
*
- * Returns: (transfer none)
+ * Returns: (transfer none): the UUID of the video capture device
*/
const gchar *
@@ -616,7 +664,8 @@ cheese_camera_device_get_id (CheeseCameraDevice *device)
return priv->id;
}
-/** cheese_camera_device_get_src:
+/**
+ * cheese_camera_device_get_src:
* @device: a #CheeseCameraDevice
*
* Returns: (transfer none)
@@ -631,10 +680,12 @@ cheese_camera_device_get_src (CheeseCameraDevice *device)
return priv->src;
}
-/** cheese_camera_device_get_device_file:
+/**
+ * cheese_camera_device_get_device_file:
* @device: a #CheeseCameraDevice
*
- * Returns: (transfer none)
+ * Returns: (transfer none): the path to the device node of the video capture
+ * device
*/
const gchar *
@@ -646,7 +697,8 @@ cheese_camera_device_get_device_file (CheeseCameraDevice *device)
return priv->device;
}
-/** cheese_camera_device_get_device_file:
+/**
+ * cheese_camera_device_get_best_format:
* @device: a #CheeseCameraDevice
*
* Returns: (transfer full): a #CheeseVideoFormat
@@ -662,8 +714,10 @@ cheese_camera_device_get_best_format (CheeseCameraDevice *device)
return format;
}
-/** cheese_camera_device_get_device_file:
+/**
+ * cheese_camera_device_get_caps_for_format:
* @device: a #CheeseCameraDevice
+ * @format: a #CheeseVideoFormat
*
* Returns: (transfer full)
*/
diff --git a/libcheese/cheese-camera-device.h b/libcheese/cheese-camera-device.h
index 843a28c..6874b93 100644
--- a/libcheese/cheese-camera-device.h
+++ b/libcheese/cheese-camera-device.h
@@ -38,15 +38,30 @@ G_BEGIN_DECLS
#define CHEESE_CAMERA_DEVICE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), CHEESE_TYPE_CAMERA_DEVICE, \
CheeseCameraDeviceClass))
-typedef struct
-{
- GObject parent;
-} CheeseCameraDevice;
+typedef struct _CheeseCameraDeviceClass CheeseCameraDeviceClass;
+typedef struct _CheeseCameraDevice CheeseCameraDevice;
-typedef struct
+/**
+ * CheeseCameraDeviceClass:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseCameraDeviceClass
{
+ /*< private >*/
GObjectClass parent_class;
-} CheeseCameraDeviceClass;
+};
+
+/**
+ * CheeseCameraDevice:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseCameraDevice
+{
+ /*< private >*/
+ GObject parent;
+};
#define CHEESE_TYPE_VIDEO_FORMAT (cheese_video_format_get_type ())
diff --git a/libcheese/cheese-effect.c b/libcheese/cheese-effect.c
index 24e9fbb..467f2cb 100644
--- a/libcheese/cheese-effect.c
+++ b/libcheese/cheese-effect.c
@@ -21,6 +21,16 @@
#include "cheese-effect.h"
+/**
+ * SECTION:cheese-effect
+ * @short_description: An effect to apply to a video capture stream
+ * @stability: Unstable
+ * @include: cheese/cheese-effect.h
+ *
+ * #CheeseEffect provides an abstraction of an effect to apply to a stream
+ * from a video capture device.
+ */
+
enum
{
PROP_O,
@@ -102,18 +112,35 @@ cheese_effect_class_init (CheeseEffectClass *klass)
object_class->get_property = cheese_effect_get_property;
object_class->set_property = cheese_effect_set_property;
+ /**
+ * CheeseEffect:name:
+ *
+ * Name of the effect.
+ */
g_object_class_install_property (object_class, PROP_NAME,
g_param_spec_string ("name",
NULL,
NULL,
"",
G_PARAM_READWRITE));
+
+ /**
+ * CheeseEffect:pipeline-desc:
+ *
+ * Description of the GStreamer pipeline associated with the effect.
+ */
g_object_class_install_property (object_class, PROP_PIPELINE_DESC,
g_param_spec_string ("pipeline_desc",
NULL,
NULL,
"",
G_PARAM_READWRITE));
+
+ /**
+ * CheeseEffect:control-valve:
+ *
+ * TODO.
+ */
g_object_class_install_property (object_class, PROP_CONTROL_VALVE,
g_param_spec_object ("control_valve",
NULL,
@@ -130,18 +157,30 @@ cheese_effect_is_preview_connected (CheeseEffect *self)
return priv->control_valve != NULL;
}
+/**
+ * cheese_effect_enable_preview:
+ * @effect: the #CheeseEffect to enable the preview of
+ *
+ * Enable the preview of a #CheeseEffect.
+ */
void
-cheese_effect_enable_preview (CheeseEffect *self)
+cheese_effect_enable_preview (CheeseEffect *effect)
{
- CheeseEffectPrivate *priv = CHEESE_EFFECT_GET_PRIVATE (self);
+ CheeseEffectPrivate *priv = CHEESE_EFFECT_GET_PRIVATE (effect);
g_object_set (G_OBJECT (priv->control_valve), "drop", FALSE, NULL);
}
+/**
+ * cheese_effect_disable_preview:
+ * @effect: the #CheeseEffect to disable the preview of
+ *
+ * Disable the preview of a #CheeseEffect.
+ */
void
-cheese_effect_disable_preview (CheeseEffect *self)
+cheese_effect_disable_preview (CheeseEffect *effect)
{
- CheeseEffectPrivate *priv = CHEESE_EFFECT_GET_PRIVATE (self);
+ CheeseEffectPrivate *priv = CHEESE_EFFECT_GET_PRIVATE (effect);
g_object_set (G_OBJECT (priv->control_valve), "drop", TRUE, NULL);
}
@@ -151,6 +190,13 @@ cheese_effect_init (CheeseEffect *self)
{
}
+/**
+ * cheese_effect_new:
+ *
+ * Create a new #CheeseEffect.
+ *
+ * Returns: (transfer full): a new #CheeseEffect
+ */
CheeseEffect *
cheese_effect_new (void)
{
@@ -158,9 +204,11 @@ cheese_effect_new (void)
}
/**
- * cheese_effect_load_from_file: load effect from file
+ * cheese_effect_load_from_file:
* @fname: (type filename): name of the file containing effect specification
*
+ * Load effect from file.
+ *
* Returns: (transfer full): a #CheeseEffect
*/
CheeseEffect*
@@ -261,7 +309,9 @@ cheese_effect_load_effects_from_subdirectory (const gchar* directory,
}
/**
- * cheese_effect_load_effects: load effects from known standard directories.
+ * cheese_effect_load_effects:
+ *
+ * Load effects from known standard directories.
*
* Returns: (element-type Cheese.Effect) (transfer full): List of #CheeseEffect
*/
diff --git a/libcheese/cheese-effect.h b/libcheese/cheese-effect.h
index 4f4c662..db0e85a 100644
--- a/libcheese/cheese-effect.h
+++ b/libcheese/cheese-effect.h
@@ -41,22 +41,37 @@ G_BEGIN_DECLS
#define CHEESE_EFFECT_GET_CLASS(obj) \
(G_TYPE_INSTANCE_GET_CLASS ((obj), CHEESE_TYPE_EFFECT, CheeseEffectClass))
-typedef struct
-{
- GObject parent;
-} CheeseEffect;
+typedef struct _CheeseEffectClass CheeseEffectClass;
+typedef struct _CheeseEffect CheeseEffect;
-typedef struct
+/**
+ * CheeseEffectClass:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseEffectClass
{
+ /*< private >*/
GObjectClass parent_class;
-} CheeseEffectClass;
+};
+
+/**
+ * CheeseEffect:
+ *
+ * Use the accessor functions below.
+ */
+struct _CheeseEffect
+{
+ /*< private >*/
+ GObject parent;
+};
GType cheese_effect_get_type (void);
CheeseEffect *cheese_effect_new (void);
-gboolean cheese_effect_is_preview_connected (CheeseEffect *self);
-void cheese_effect_enable_preview (CheeseEffect *self);
-void cheese_effect_disable_preview (CheeseEffect *self);
+gboolean cheese_effect_is_preview_connected (CheeseEffect *effect);
+void cheese_effect_enable_preview (CheeseEffect *effect);
+void cheese_effect_disable_preview (CheeseEffect *effect);
CheeseEffect *cheese_effect_load_from_file (const gchar *fname);
GList *cheese_effect_load_effects (void);
diff --git a/libcheese/cheese-widget.c b/libcheese/cheese-widget.c
index 0f7bd5f..c75cae3 100644
--- a/libcheese/cheese-widget.c
+++ b/libcheese/cheese-widget.c
@@ -28,6 +28,16 @@
#include "cheese-enums.h"
#include "cheese-aspect-frame.h"
+/**
+ * SECTION:cheese-widget
+ * @short_description: A photo/video capture widget.
+ * @stability: Unstable
+ * @include: cheese/cheese-widget.h
+ *
+ * #CheeseWidget provides a basic photo and video capture widget, for embedding
+ * in an application.
+ */
+
enum
{
READY_SIGNAL,
diff --git a/libcheese/cheese-widget.h b/libcheese/cheese-widget.h
index 86dbc62..220b79f 100644
--- a/libcheese/cheese-widget.h
+++ b/libcheese/cheese-widget.h
@@ -40,13 +40,25 @@ G_BEGIN_DECLS
typedef struct _CheeseWidgetClass CheeseWidgetClass;
typedef struct _CheeseWidget CheeseWidget;
+/**
+ * CheeseWidgetClass:
+ *
+ * Use the accessor functions below.
+ */
struct _CheeseWidgetClass
{
+ /*< private >*/
GtkNotebookClass parent_class;
};
+/**
+ * CheeseWidget:
+ *
+ * Use the accessor functions below.
+ */
struct _CheeseWidget
{
+ /*< private >*/
GtkNotebook parent_instance;
};
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
