[libyelp] Adding gtk-doc API reference

52a6d22d · Shaun McCance · 33e1b4f7 · 52a6d22d · 52a6d22d · 52a6d22d
Commit 52a6d22d authored Oct 01, 2009 by Shaun McCance
10 changed files
--- 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
--- 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}

--- a/docs/Makefile.am
+++ b/docs/Makefile.am
+SUBDIRS = libyelp
--- a/docs/libyelp/Makefile.am
+++ b/docs/libyelp/Makefile.am
+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
--- a/docs/libyelp/libyelp-docs.xml
+++ b/docs/libyelp/libyelp-docs.xml
+<?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>
--- a/docs/libyelp/version.xml.in
+++ b/docs/libyelp/version.xml.in
+@VERSION@
--- a/libyelp/Makefile.am
+++ b/libyelp/Makefile.am
-noinst_LTLIBRARIES = libyelp.la
+lib_LTLIBRARIES = libyelp.la

 libyelp_la_SOURCES =				\
 	yelp-debug.c				\

--- 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

--- 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)
 {

--- 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__ */