[cheese] Add API docs through gtk-doc for libcheese-gtk
- From: Bastien Nocera <hadess src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [cheese] Add API docs through gtk-doc for libcheese-gtk
- Date: Tue, 12 Jan 2010 15:13:00 +0000 (UTC)
commit 82fc079caad734eaaf33c70c6844e1929de07dee
Author: Bastien Nocera <hadess hadess net>
Date: Tue Jan 12 15:12:36 2010 +0000
Add API docs through gtk-doc for libcheese-gtk
Makefile.am | 4 +-
configure.ac | 5 ++
docs/Makefile.am | 1 +
docs/reference/Makefile.am | 95 +++++++++++++++++++++++++++++++++++++
docs/reference/version.xml.in | 1 +
libcheese/cheese-avatar-chooser.c | 23 +++++++++-
libcheese/cheese-gtk.symbols | 1 -
libcheese/cheese-widget-private.h | 31 ++++++++++++
libcheese/cheese-widget.c | 23 +++++++++
libcheese/cheese-widget.h | 2 -
10 files changed, 180 insertions(+), 6 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index c241154..875108f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,4 +1,4 @@
-SUBDIRS = libcheese src tests po data help
+SUBDIRS = libcheese src tests po data help docs
EXTRA_DIST = \
$(cheesedoc_DATA) \
@@ -13,7 +13,7 @@ DISTCLEANFILES = \
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = cheese-gtk.pc
-DISTCHECK_CONFIGURE_FLAGS = --disable-schemas-install --disable-scrollkeeper
+DISTCHECK_CONFIGURE_FLAGS = --disable-schemas-install --disable-scrollkeeper --enable-gtk-doc
CHANGELOG_START = 2.26.0
diff --git a/configure.ac b/configure.ac
index f6712ce..a828d48 100644
--- a/configure.ac
+++ b/configure.ac
@@ -21,6 +21,8 @@ CFLAGS="${CFLAGS} -Wall"
GNOME_MAINTAINER_MODE_DEFINES
GNOME_COMPILE_WARNINGS
+GTK_DOC_CHECK(1.11)
+
#*******************************************************************************
# soname
#*******************************************************************************
@@ -134,6 +136,9 @@ AM_GCONF_SOURCE_2
AC_OUTPUT([
Makefile
cheese-gtk.pc
+docs/Makefile
+docs/reference/Makefile
+docs/reference/version.xml
data/Makefile
data/cheese.desktop.in
data/effects/Makefile
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..f3ddc22
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = reference
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644
index 0000000..20f8594
--- /dev/null
+++ b/docs/reference/Makefile.am
@@ -0,0 +1,95 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=cheese
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=../../libcheese
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml --name-space=totem_pl_parser
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Add the builddir to the HTML path so that version.xml is found
+MKHTML_OPTIONS=--path="$(abs_builddir)"
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(top_srcdir)/libcheese/*.h
+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-device-monitor.h \
+ cheese-camera.h \
+ cheese-countdown.h \
+ cheese-fileutil.h \
+ cheese-flash.h \
+ cheese-gconf.h \
+ cheese-widget-private.h \
+ um-crop-area.h
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=version.xml
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# 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
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += version.xml.in
+
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = cd $(srcdir) &&
+TESTS = $(GTKDOC_CHECK)
+endif
diff --git a/docs/reference/version.xml.in b/docs/reference/version.xml.in
new file mode 100644
index 0000000..d78bda9
--- /dev/null
+++ b/docs/reference/version.xml.in
@@ -0,0 +1 @@
+ VERSION@
diff --git a/libcheese/cheese-avatar-chooser.c b/libcheese/cheese-avatar-chooser.c
index 62ee0fb..d162118 100644
--- a/libcheese/cheese-avatar-chooser.c
+++ b/libcheese/cheese-avatar-chooser.c
@@ -23,7 +23,7 @@
#include <canberra-gtk.h>
#include "cheese-camera.h"
-#include "cheese-widget.h"
+#include "cheese-widget-private.h"
#include "cheese-countdown.h"
#include "cheese-flash.h"
#include "cheese-avatar-chooser.h"
@@ -313,6 +313,11 @@ cheese_avatar_chooser_class_init (CheeseAvatarChooserClass *klass)
dialog_class->response = cheese_avatar_chooser_response;
object_class->get_property = cheese_avatar_chooser_get_property;
+ /**
+ * CheeseAvatarChooser:pixbuf:
+ *
+ * a #GdkPixbuf object representing the cropped area of the picture, or %NULL.
+ **/
g_object_class_install_property (object_class, PROP_PIXBUF,
g_param_spec_object ("pixbuf",
NULL,
@@ -323,12 +328,28 @@ cheese_avatar_chooser_class_init (CheeseAvatarChooserClass *klass)
g_type_class_add_private (klass, sizeof (CheeseAvatarChooserPrivate));
}
+/**
+ * cheese_avatar_chooser_new:
+ *
+ * Returns a new #CheeseAvatarChooser dialogue.
+ *
+ * Return value: a #CheeseAvatarChooser widget.
+ **/
GtkWidget *
cheese_avatar_chooser_new (void)
{
return g_object_new (CHEESE_TYPE_AVATAR_CHOOSER, NULL);
}
+/**
+ * cheese_avatar_chooser_get_picture:
+ * @chooser: a #CheeseAvatarChooser dialogue.
+ *
+ * Returns the portion of image selected through the builtin
+ * cropping tool, after a picture has been captured on the webcam.
+ *
+ * Return value: a #GdkPixbuf object, or %NULL if no picture has been taken yet.
+ **/
GdkPixbuf *
cheese_avatar_chooser_get_picture (CheeseAvatarChooser *chooser)
{
diff --git a/libcheese/cheese-gtk.symbols b/libcheese/cheese-gtk.symbols
index 5a24aa3..d42d0c5 100644
--- a/libcheese/cheese-gtk.symbols
+++ b/libcheese/cheese-gtk.symbols
@@ -1,6 +1,5 @@
cheese_widget_get_type
cheese_widget_new
-cheese_widget_get_camera
cheese_avatar_chooser_get_type
cheese_avatar_chooser_new
cheese_avatar_chooser_get_picture
diff --git a/libcheese/cheese-widget-private.h b/libcheese/cheese-widget-private.h
new file mode 100644
index 0000000..5fd40b7
--- /dev/null
+++ b/libcheese/cheese-widget-private.h
@@ -0,0 +1,31 @@
+/*
+ * Copyright © 2009 Bastien Nocera <hadess hadess net>
+ *
+ * Licensed under the GNU General Public License Version 2
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef _CHEESE_WIDGET_PRIVATE_H_
+#define _CHEESE_WIDGET_PRIVATE_H_
+
+#include "cheese-widget.h"
+
+G_BEGIN_DECLS
+
+GObject *cheese_widget_get_camera (CheeseWidget *widget);
+
+G_END_DECLS
+
+#endif /* _CHEESE_WIDGET_PRIVATE_H_ */
diff --git a/libcheese/cheese-widget.c b/libcheese/cheese-widget.c
index a6c92e1..4a6a126 100644
--- a/libcheese/cheese-widget.c
+++ b/libcheese/cheese-widget.c
@@ -404,6 +404,14 @@ cheese_widget_class_init (CheeseWidgetClass *klass)
#endif
widget_class->realize = cheese_widget_realize;
+ /**
+ * CheeseWidget::ready:
+ *
+ * @is_ready: Whether the camera is ready for use by the widget.
+ *
+ * The ::ready signal is emitted when the camera is ready to be
+ * used by the widget and other applications.
+ */
widget_signals[READY_SIGNAL] = g_signal_new ("ready", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseWidgetClass, ready),
@@ -411,6 +419,14 @@ cheese_widget_class_init (CheeseWidgetClass *klass)
g_cclosure_marshal_VOID__BOOLEAN,
G_TYPE_NONE, 1, G_TYPE_BOOLEAN);
+ /**
+ * CheeseWidget::error:
+ *
+ * @error: The error message.
+ *
+ * The ::error signal is emitted when the widget cannot access
+ * the camera.
+ */
widget_signals[ERROR_SIGNAL] = g_signal_new ("error", G_OBJECT_CLASS_TYPE (klass),
G_SIGNAL_RUN_LAST | G_SIGNAL_ACTION,
G_STRUCT_OFFSET (CheeseWidgetClass, error),
@@ -421,6 +437,13 @@ cheese_widget_class_init (CheeseWidgetClass *klass)
g_type_class_add_private (klass, sizeof (CheeseWidgetPrivate));
}
+/**
+ * cheese_widget_new:
+ *
+ * Returns a new #CheeseWidget widget.
+ *
+ * Return value: a #CheeseWidget widget.
+ **/
GtkWidget *
cheese_widget_new (void)
{
diff --git a/libcheese/cheese-widget.h b/libcheese/cheese-widget.h
index cb82818..b8872ea 100644
--- a/libcheese/cheese-widget.h
+++ b/libcheese/cheese-widget.h
@@ -55,8 +55,6 @@ GType cheese_widget_get_type (void) G_GNUC_CONST;
GtkWidget *cheese_widget_new (void);
-GObject *cheese_widget_get_camera (CheeseWidget *widget);
-
G_END_DECLS
#endif /* _CHEESE_WIDGET_H_ */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]