GNOME.org
 

[cheese] Add API docs through gtk-doc for libcheese-gtk

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]