GNOME.org
 

[yelp/yelp-3-0] [libyelp] Adding gtk-doc API reference

commit 52a6d22da30e40042fff1c5899c9969cff12bfd5
Author: Shaun McCance <shaunm gnome org>
Date:   Thu Oct 1 17:04:07 2009 -0500

    [libyelp] Adding gtk-doc API reference

 Makefile.am                   |   10 ++--
 configure.in                  |   19 +++++--
 docs/Makefile.am              |    1 +
 docs/libyelp/Makefile.am      |   79 +++++++++++++++++++++++++++
 docs/libyelp/libyelp-docs.xml |   41 ++++++++++++++
 docs/libyelp/version.xml.in   |    1 +
 libyelp/Makefile.am           |    2 +-
 libyelp/yelp-debug.c          |    2 +-
 libyelp/yelp-location-entry.c |  118 ++++++++++++++++++++++++++++++++---------
 libyelp/yelp-location-entry.h |   19 ++++++-
 10 files changed, 253 insertions(+), 39 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index 5752cdb..f178f2e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -18,11 +18,11 @@ EXTRA_DIST = 						\
 	important_docs.xml				\
 	$(desktop_in_files)
 
-DISTCLEANFILES = \
-  intltool-extract \
-  intltool-merge \
-  intltool-update
+DISTCLEANFILES = 					\
+	intltool-extract 				\
+	intltool-merge 					\
+	intltool-update
 
 CLEANFILES = $(desktop_DATA)
 
-DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper
+DISTCHECK_CONFIGURE_FLAGS = --disable-scrollkeeper --enable-gtk-doc
diff --git a/configure.in b/configure.in
index 20cfde0..a626a82 100644
--- a/configure.in
+++ b/configure.in
@@ -8,12 +8,9 @@ AC_CONFIG_HEADERS([config.h])
 AM_INIT_AUTOMAKE([1.9 dist-bzip2 no-dist-gzip])
 AM_MAINTAINER_MODE
 
-AC_SUBST(ACLOCAL_AMFLAGS, "\${ACLOCAL_FLAGS}")
-
-IT_PROG_INTLTOOL([0.35.0])
-AC_PATH_PROG(GCONFTOOL, gconftool-2)
+AC_CONFIG_MACRO_DIR(m4)
 
-AM_GCONF_SOURCE_2
+AC_SUBST(ACLOCAL_AMFLAGS, "\${ACLOCAL_FLAGS}")
 
 AC_PROG_LN_S
 AC_PROG_CC
@@ -22,9 +19,15 @@ AC_ISC_POSIX
 AC_HEADER_STDC
 AM_PROG_LIBTOOL
 AM_PATH_GLIB_2_0
-
 AM_PROG_CC_C_O
 
+IT_PROG_INTLTOOL([0.35.0])
+
+GTK_DOC_CHECK(1.9)
+
+AC_PATH_PROG(GCONFTOOL, gconftool-2)
+AM_GCONF_SOURCE_2
+
 GNOME_DEBUG_CHECK
 GNOME_COMPILE_WARNINGS([maximum])
 
@@ -253,6 +256,9 @@ AC_SUBST([AM_LDFLAGS])
 
 AC_CONFIG_FILES([
 Makefile
+docs/Makefile
+docs/libyelp/Makefile
+docs/libyelp/version.xml
 libyelp/Makefile
 src/Makefile
 stylesheets/Makefile
@@ -278,6 +284,7 @@ yelp-$VERSION:
 	source code location:	  ${srcdir}
 	compiler:		  ${CC}
 
+	Documentation:            ${enable_gtk_doc}
 	Debug enabled:            ${enable_debug}
 	Search backend:           ${search_backend}
 	Using SMClient:           ${with_smclient}
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..99b6b71
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = libyelp
diff --git a/docs/libyelp/Makefile.am b/docs/libyelp/Makefile.am
new file mode 100644
index 0000000..dd54bd0
--- /dev/null
+++ b/docs/libyelp/Makefile.am
@@ -0,0 +1,79 @@
+AUTOMAKE_OPTIONS = 1.6
+
+DOC_MODULE = libyelp
+
+DOC_MAIN_SGML_FILE = libyelp-docs.xml
+
+SCAN_OPTIONS = --deprecated-guards="G_DISABLE_DEPRECATED" --rebuild-types
+
+SCANGOBJ_OPTIONS = --type-init-func="g_type_init();g_thread_init(NULL);"
+
+DOC_SOURCE_DIR = $(top_srcdir)/libyelp
+
+GTKDOC_CFLAGS =						\
+	$(YELP_CFLAGS)					\
+	-I$(top_srcdir)/libyelp
+
+GTKDOC_LIBS =						\
+	$(YELP_LIBS)					\
+	$(top_builddir)/libyelp/libyelp.la
+
+HFILE_GLOB = $(top_srcdir)/libyelp/*.h
+CFILE_GLOB = $(top_srcdir)/libyelp/*.c
+IGNORE_HFILES = yelp-debug.h
+
+MKDB_OPTIONS = --output-format=xml --sgml-mode --name-space=yelp --ignore-files='yelp-debug.h yelp-debug.c'
+
+content_files = version.xml
+
+extra_viles = version.xml.in
+
+include $(top_srcdir)/gtk-doc.make
+
+EXTRA_DIST += version.xm.in
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+#MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkhtml
+#MKHTML_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=
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+#EXTRA_HFILES=
+
+
+# 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=
+
+# 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=
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+#EXTRA_DIST +=
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+#DISTCLEANFILES +=
+
+# Comment this out if you want your docs-status tested during 'make check'
+#if ENABLE_GTK_DOC
+#TESTS_ENVIRONMENT = cd $(srcsrc) &&
+#TESTS = $(GTKDOC_CHECK)
+#endif
diff --git a/docs/libyelp/libyelp-docs.xml b/docs/libyelp/libyelp-docs.xml
new file mode 100644
index 0000000..77fcf52
--- /dev/null
+++ b/docs/libyelp/libyelp-docs.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+  <bookinfo>
+    <title>Yelp Reference Manual</title>
+    <releaseinfo>for libyelp &version;</releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>API Reference</title>
+    <section>
+      <title>Widgets</title>
+      <include href="xml/yelp-view.xml" xmlns="http://www.w3.org/2003/XInclude"/>
+      <include href="xml/yelp-location-entry.xml" xmlns="http://www.w3.org/2003/XInclude"/>
+    </section>
+    <section>
+      <title>Document Processing</title>
+      <include href="xml/yelp-document.xml" xmlns="http://www.w3.org/2003/XInclude"/>
+      <include href="xml/yelp-simple-document.xml" xmlns="http://www.w3.org/2003/XInclude"/>
+    </section>
+
+    <include href="xml/yelp-uri.xml" xmlns="http://www.w3.org/2003/XInclude"/>
+    <include href="xml/yelp-settings.xml" xmlns="http://www.w3.org/2003/XInclude"/>
+    <include href="xml/yelp-error.xml" xmlns="http://www.w3.org/2003/XInclude"/>
+
+  </chapter>
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+     <include href="xml/tree_index.sgml" xmlns="http://www.w3.org/2003/XInclude"/>
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <include href="xml/api-index-full.xml" xmlns="http://www.w3.org/2003/XInclude";><fallback/></include>
+  </index>
+
+  <include href="xml/annotation-glossary.xml" xmlns="http://www.w3.org/2003/XInclude";><fallback/></include>
+</book>
diff --git a/docs/libyelp/version.xml.in b/docs/libyelp/version.xml.in
new file mode 100644
index 0000000..d78bda9
--- /dev/null
+++ b/docs/libyelp/version.xml.in
@@ -0,0 +1 @@
+ VERSION@
diff --git a/libyelp/Makefile.am b/libyelp/Makefile.am
index c1946a8..69e6e9a 100644
--- a/libyelp/Makefile.am
+++ b/libyelp/Makefile.am
@@ -1,4 +1,4 @@
-noinst_LTLIBRARIES = libyelp.la
+lib_LTLIBRARIES = libyelp.la
 
 libyelp_la_SOURCES =				\
 	yelp-debug.c				\
diff --git a/libyelp/yelp-debug.c b/libyelp/yelp-debug.c
index 744a3c8..7a12dde 100644
--- a/libyelp/yelp-debug.c
+++ b/libyelp/yelp-debug.c
@@ -27,7 +27,7 @@
 
 #include "yelp-debug.h"
 
-/**
+/*
  * @file:     you should pass the __FILE__ constant as this parameter
  * @line:     you should pass the __LINE__ constant as this parameter
  * @function: you should pass the __FUNCTION__ constant as this parameter
diff --git a/libyelp/yelp-location-entry.c b/libyelp/yelp-location-entry.c
index c089eb1..6b9ba01 100644
--- a/libyelp/yelp-location-entry.c
+++ b/libyelp/yelp-location-entry.c
@@ -26,20 +26,37 @@
 
 #include "yelp-location-entry.h"
 
-struct _YelpLocationEntryPrivate
-{
-    GtkWidget *text_entry;
-
-    gint       icon_column;
-    gint       flags_column;
-    gboolean   enable_search;
-
-    GtkTreeRowReference *row;
-
-    gboolean   search_mode;
-
-    GtkCellRenderer *icon_cell;
-};
+/**
+ * SECTION:yelp-location-entry
+ * @short_description: A location entry with history and search
+ * @include: yelp.h
+ *
+ * #YelpLocationEntry is a #GtkComboBoxEntry designed to show the current location,
+ * provide a drop-down menu of previous locations, and allow the user to perform
+ * searches.
+ *
+ * The #GtkTreeModel used by a #YelpLocationEntry is expected to have at least
+ * three columns: #GtkComboBoxEntry::text-column contains the displayed name
+ * of the location, #YelpLocationEntry::icon-column contains an icon name for
+ * the location, and #YelpLocationEntry::flags-column contains a bit field
+ * of #YelpLocationEntryFlags.  These columns are specified when creating a
+ * #YelpLocationEntry widget with yelp_location_entry_new_with_model().
+ *
+ * Usually, a single row in the #GtkTreeModel corresponds to a location.  When
+ * a user selects a row from the drop-down menu, the icon and text for that
+ * row will be placed in the embedded text entry, and the
+ * #YelpLocationEntry:location-selected signal will be emitted.
+ *
+ * If a row has the %YELP_LOCATION_ENTRY_IS_SEARCH flag set, selecting that
+ * row will not emit the #YelpLocationEntry::location-selected signal.  Instead,
+ * the #YelpLocationEntry widget will be placed into search mode, as if by a
+ * call to yelp_location_entry_start_search().
+ *
+ * When a row has the %YELP_LOCATION_ENTRY_CAN_BOOKMARK flag set, an icon
+ * will be displayed in the secondary icon position of the embedded text
+ * entry allowing the user to bookmark the location.  Clicking this icon
+ * will cause the FIXME signal to be emitted.
+ **/
 
 static void     location_entry_get_property    (GObject           *object,
                                                 guint              prop_id,
@@ -85,6 +102,20 @@ static gboolean entry_key_press_cb                  (GtkWidget         *widget,
                                                      GdkEventKey       *event,
                                                      gpointer           user_data);
 
+struct _YelpLocationEntryPrivate
+{
+    GtkWidget *text_entry;
+
+    gint       icon_column;
+    gint       flags_column;
+    gboolean   enable_search;
+
+    GtkTreeRowReference *row;
+
+    gboolean   search_mode;
+
+    GtkCellRenderer *icon_cell;
+};
 
 enum {
   LOCATION_SELECTED,
@@ -116,8 +147,14 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
 
     /**
      * YelpLocationEntry::location-selected
-     * @widget: The object which received the signal
-     */
+     * @widget: The #YelpLocationEntry for which the signal was emitted.
+     * @user_data: User data set when the handler was connected.
+     *
+     * This signal will be emitted whenever a user selects a normal row from the
+     * drop-down menu.  Note that if a row has the flag %YELP_LOCATION_ENTRY_IS_SEARCH,
+     * clicking the row will cause @widget to enter search mode, and this signal
+     * will not be emitted.
+     **/
     location_entry_signals[LOCATION_SELECTED] =
         g_signal_new ("location_selected",
                       G_OBJECT_CLASS_TYPE (klass),
@@ -127,10 +164,15 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
                       G_TYPE_NONE, 0);
 
     /**
-     * YelpLocationEntry::search_activated
-     * @widget: The object which received the signal
-     * @text: The search text
-     */
+     * YelpLocationEntry::search-activated
+     * @widget: The #YelpLocationEntry for which the signal was emitted.
+     * @text: The search text.
+     * @user_data: User data set when the handler was connected.
+     *
+     * This signal will be emitted whenever the user activates a search, generally
+     * by pressing <keycap>Enter</keycap> in the embedded text entry while @widget
+     * is in search mode.
+     **/
     location_entry_signals[SEARCH_ACTIVATED] =
         g_signal_new ("search-activated",
                       G_OBJECT_CLASS_TYPE (klass),
@@ -140,6 +182,12 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
                       G_TYPE_NONE, 1,
                       G_TYPE_STRING);
 
+    /**
+     * YelpLocationEntry:icon-column
+     *
+     * The column in the #GtkTreeModel containing an icon name for each row.
+     * This must be a name that can be looked up through #GtkIconTheme.
+     **/
     g_object_class_install_property (object_class,
                                      PROP_ICON_COLUMN,
                                      g_param_spec_int ("icon-column",
@@ -150,6 +198,12 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
                                                        -1,
                                                        G_PARAM_READWRITE | G_PARAM_STATIC_NAME |
                                                        G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
+    /**
+     * YelpLocationEntry:flags-column
+     *
+     * The column in the #GtkTreeModel containing #YelpLocationEntryFlags flags
+     * for each row.
+     **/
     g_object_class_install_property (object_class,
                                      PROP_FLAGS_COLUMN,
                                      g_param_spec_int ("flags-column",
@@ -160,6 +214,13 @@ yelp_location_entry_class_init (YelpLocationEntryClass *klass)
                                                        -1,
                                                        G_PARAM_READWRITE | G_PARAM_STATIC_NAME |
                                                        G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
+    /**
+     * YelpLocationEntry:enable-search
+     *
+     * Whether the location entry can act as a search entry.  If search is not
+     * enabled, the user will not be able to initiate a search by clicking in
+     * the embedded text entry or selecting a search row in the drop-down menu.
+     **/
     g_object_class_install_property (object_class,
                                      PROP_ENABLE_SEARCH,
                                      g_param_spec_boolean ("enable-search",
@@ -545,17 +606,16 @@ entry_key_press_cb (GtkWidget   *widget,
 }
 
 /**
- * yelp_location_entry_ew_with_model:
+ * yelp_location_entry_new_with_model:
  * @model: A #GtkTreeModel.
  * @text_column: The column in @model containing the title of each entry.
  * @icon_column: The column in @model containing the icon name of each entry.
- * @bookmark_column: The column in @model containing a gboolean specifying
- * whether or not each entry is bookmarked.
+ * @flags_column: The column in @model containing #YelpLocationEntryFlags.
  *
  * Creates a new #YelpLocationEntry widget.
  *
- * Return value: A new #YelpLocationEntry.
- */
+ * Returns: A new #YelpLocationEntry.
+ **/
 GtkWidget*
 yelp_location_entry_new_with_model (GtkTreeModel *model,
                                     gint          text_column,
@@ -581,6 +641,14 @@ yelp_location_entry_new_with_model (GtkTreeModel *model,
     return ret;
 }
 
+/**
+ * yelp_location_entry_start_search:
+ * @entry: A #YelpLocationEntry.
+ *
+ * Puts @entry into search mode.  This focuses the entry and clears its text
+ * contents.  When the user activates the search, the
+ * #YelpLocationEntry::search-activated signal will be emitted.
+ **/
 void
 yelp_location_entry_start_search (YelpLocationEntry *entry)
 {
diff --git a/libyelp/yelp-location-entry.h b/libyelp/yelp-location-entry.h
index 3116be2..8ee2792 100644
--- a/libyelp/yelp-location-entry.h
+++ b/libyelp/yelp-location-entry.h
@@ -42,6 +42,9 @@ G_BEGIN_DECLS
   (G_TYPE_INSTANCE_GET_CLASS((obj), YELP_TYPE_LOCATION_ENTRY, \
 			     YelpLocationEntryClass))
 
+/**
+ * YelpLocationEntry:
+ **/
 typedef struct _YelpLocationEntry         YelpLocationEntry;
 typedef struct _YelpLocationEntryClass    YelpLocationEntryClass;
 typedef struct _YelpLocationEntryPrivate  YelpLocationEntryPrivate;
@@ -57,6 +60,20 @@ struct _YelpLocationEntryClass
     GtkComboBoxEntryClass     parent;
 };
 
+/**
+ * YelpLocationEntryFlags:
+ * @YELP_LOCATION_ENTRY_CAN_BOOKMARK: This location can be bookmarked.  When a
+ * bookmarkable location is selected, the secondary icon of the embedded text
+ * entry will be a clickable bookmark icon.
+ * @YELP_LOCATION_ENTRY_IS_LOADING: Page data for this location is still loading.
+ * The #YelpLocationEntry widget will display an indeterminate progress indicator.
+ * @YELP_LOCATION_ENTRY_IS_SEPARATOR: This row should be displayed as a separator.
+ * @YELP_LOCATION_ENTRY_IS_SEARCH: Selecting this row initiates a search instead
+ * of selecting a location.
+ *
+ * Flags which can be used to provide additional information about rows
+ * to be displayed by a #YelpLocationEntry.
+ **/
 typedef enum {
     YELP_LOCATION_ENTRY_CAN_BOOKMARK = 1 << 0,
     YELP_LOCATION_ENTRY_IS_LOADING   = 1 << 1,
@@ -74,4 +91,4 @@ void            yelp_location_entry_start_search    (YelpLocationEntry *entry);
 
 G_END_DECLS
 
-#endif /* __YELP_DOCUMENT_H__ */
+#endif /* __YELP_LOCATION_ENTRY_H__ */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]