reviewed by: Alex Larsson

2006-04-11  Sven Herzberg  <herzi@gnome-de.org>

        reviewed by: Alex Larsson

	* Makefile.am: added the reference subdirectory
	* autogen.sh: enable gtk-doc for developer builds (necessary for dist)
	* configure.in: check for gtk-doc, set distcheck flags, build the
	Makefile
	* gnome-keyring.c: documented gnome_keyring_find_items_sync()
	* reference/Makefile.am: documentation build system
	* reference/gnome-keyring-docs.sgml: rough documentation framework
	* reference/gnome-keyring-sections.txt: some documentation
	categorization (needs to be further split)

8 files changed, 259 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 96c8f90e..269251bd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2006-04-11  Sven Herzberg  <herzi@gnome-de.org>
+
+	reviewed by: Alex Larsson
+
+	* Makefile.am: added the reference subdirectory
+	* autogen.sh: enable gtk-doc for developer builds (necessary for dist)
+	* configure.in: check for gtk-doc, set distcheck flags, build the
+	Makefile
+	* gnome-keyring.c: documented gnome_keyring_find_items_sync()
+	* reference/Makefile.am: documentation build system
+	* reference/gnome-keyring-docs.sgml: rough documentation framework
+	* reference/gnome-keyring-sections.txt: some documentation
+	categorization (needs to be further split)
+
 2006-04-03  Dan Williams  <dcbw@redhat.com>
 
 	* gnome-keyring-daemon.c
diff --git a/Makefile.am b/Makefile.am
index d7c8c1b8..f8966f51 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,5 +1,6 @@
 SUBDIRS = \
-	po
+	po \
+	reference
 
 libgnomekeyringincludedir = $(includedir)/gnome-keyring-1/
 
diff --git a/autogen.sh b/autogen.sh
index d2fbefd2..3338b6b9 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -19,4 +19,4 @@ which gnome-autogen.sh || {
     echo "You need to install gnome-common from the GNOME CVS"
     exit 1
 }
-USE_GNOME2_MACROS=1 . gnome-autogen.sh
+USE_GNOME2_MACROS=1 . gnome-autogen.sh --enable-gtk-doc
diff --git a/configure.in b/configure.in
index 52df4c6d..08659957 100644
--- a/configure.in
+++ b/configure.in
@@ -25,6 +25,10 @@ AC_TYPE_SIGNAL
 AC_TYPE_SIZE_T
 AC_TYPE_UID_T
 
+GTK_DOC_CHECK
+DISTCHECK_CONFIGURE_FLAGS="--enable-gtk-doc"
+AC_SUBST(DISTCHECK_CONFIGURE_FLAGS)
+
 PKG_CHECK_MODULES(GLIB, glib-2.0 >= 2.6.0)
 PKG_CHECK_MODULES(GTK, gtk+-2.0 >= 2.6.0)
 AC_SUBST(GLIB_CFLAGS)
@@ -164,6 +168,7 @@ fi
 AC_OUTPUT([
 Makefile
 po/Makefile.in
+reference/Makefile
 gnome-keyring-1.pc
 gnome-keyring-1-uninstalled.pc
 ])
diff --git a/gnome-keyring.c b/gnome-keyring.c
index a89541d0..2befed6d 100644
--- a/gnome-keyring.c
+++ b/gnome-keyring.c
@@ -1443,6 +1443,17 @@ gnome_keyring_find_itemsv (GnomeKeyringItemType                  type,
 	return op;
 }
 
+/**
+ * gnome_keyring_find_items_sync:
+ * @type: a #GnomeKeyringItemType
+ * @attributes: a #GnomeKeyringAttributeList
+ * @found: a return location for the found items, must not be %NULL
+ *
+ * Find elements of type #GnomeKeyring by matching attributes and @type.
+ *
+ * Returns: a #GList of #GnomeKeyringFound, free with g_list_free() and
+ * gnome_keyring_found_free()
+ */
 GnomeKeyringResult
 gnome_keyring_find_items_sync (GnomeKeyringItemType        type,
 			       GnomeKeyringAttributeList  *attributes,
diff --git a/reference/Makefile.am b/reference/Makefile.am
new file mode 100644
index 00000000..06f77cc9
--- /dev/null
+++ b/reference/Makefile.am
@@ -0,0 +1,96 @@
+## Process this file with automake to produce Makefile.in
+NULL=
+
+all-recursive: all
+
+# all: tmpl.stamp
+
+# 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=gnome-keyring
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# 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=..
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=--type-init-func="g_type_init()"
+
+# 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
+
+# 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=
+
+# 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)/*.h
+CFILE_GLOB=$(top_srcdir)/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=\
+	aes_be.h \
+	aes.h \
+	aes_le.h \
+	beecrypt_compat.h \
+	config.h \
+	gnome-keyring-daemon.h \
+	gnome-keyring-private.h \
+	gnome-keyring-proto.h \
+	md5.h \
+	mkdtemp.h \
+	sha256.h \
+	$(NULL)
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=\
+	$(NULL)
+
+# 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=\
+	$(NULL)
+
+# 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=\
+	$(NULL)
+GTKDOC_LIBS=\
+	$(NULL)
+
+# 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 += 
diff --git a/reference/gnome-keyring-docs.sgml b/reference/gnome-keyring-docs.sgml
new file mode 100644
index 00000000..53e009c6
--- /dev/null
+++ b/reference/gnome-keyring-docs.sgml
@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>[Insert name here] Reference Manual</title>
+  </bookinfo>
+
+  <chapter>
+    <title>[Insert title here]</title>
+    <xi:include href="xml/gnome-keyring.xml"/>
+  </chapter>
+</book>
diff --git a/reference/gnome-keyring-sections.txt b/reference/gnome-keyring-sections.txt
new file mode 100644
index 00000000..4c60bf01
--- /dev/null
+++ b/reference/gnome-keyring-sections.txt
@@ -0,0 +1,117 @@
+<SECTION>
+<FILE>gnome-keyring</FILE>
+GnomeKeyringResult
+GnomeKeyringItemType
+GnomeKeyringAccessRestriction
+GnomeKeyringAttributeType
+GnomeKeyringAccessControl
+GnomeKeyringApplicationRef
+GnomeKeyringAttributeList
+GnomeKeyringAccessType
+GnomeKeyringInfo
+GnomeKeyringItemInfo
+GnomeKeyringAttribute
+GnomeKeyringFound
+GnomeKeyringOperationDoneCallback
+GnomeKeyringOperationGetStringCallback
+GnomeKeyringOperationGetIntCallback
+GnomeKeyringOperationGetListCallback
+GnomeKeyringOperationGetKeyringInfoCallback
+GnomeKeyringOperationGetItemInfoCallback
+GnomeKeyringOperationGetAttributesCallback
+gnome_keyring_attribute_list_index
+gnome_keyring_attribute_list_new
+gnome_keyring_attribute_list_append_string
+gnome_keyring_attribute_list_append_uint32
+gnome_keyring_attribute_list_free
+gnome_keyring_attribute_list_copy
+gnome_keyring_is_available
+gnome_keyring_free_password
+gnome_keyring_found_free
+gnome_keyring_found_list_free
+gnome_keyring_cancel_request
+gnome_keyring_set_default_keyring
+gnome_keyring_set_default_keyring_sync
+gnome_keyring_get_default_keyring
+gnome_keyring_get_default_keyring_sync
+gnome_keyring_list_keyring_names
+gnome_keyring_list_keyring_names_sync
+gnome_keyring_lock_all
+gnome_keyring_lock_all_sync
+gnome_keyring_create
+gnome_keyring_create_sync
+gnome_keyring_unlock
+gnome_keyring_unlock_sync
+gnome_keyring_lock
+gnome_keyring_lock_sync
+gnome_keyring_delete
+gnome_keyring_delete_sync
+gnome_keyring_get_info
+gnome_keyring_get_info_sync
+gnome_keyring_set_info
+gnome_keyring_set_info_sync
+gnome_keyring_list_item_ids
+gnome_keyring_list_item_ids_sync
+gnome_keyring_info_free
+gnome_keyring_info_copy
+gnome_keyring_info_set_lock_on_idle
+gnome_keyring_info_get_lock_on_idle
+gnome_keyring_info_set_lock_timeout
+gnome_keyring_info_get_lock_timeout
+gnome_keyring_info_get_mtime
+gnome_keyring_info_get_ctime
+gnome_keyring_info_get_is_locked
+gnome_keyring_find_items
+gnome_keyring_find_itemsv
+gnome_keyring_find_items_sync
+gnome_keyring_find_itemsv_sync
+gnome_keyring_item_create
+gnome_keyring_item_create_sync
+gnome_keyring_item_delete
+gnome_keyring_item_delete_sync
+gnome_keyring_item_get_info
+gnome_keyring_item_get_info_sync
+gnome_keyring_item_set_info
+gnome_keyring_item_set_info_sync
+gnome_keyring_item_get_attributes
+gnome_keyring_item_get_attributes_sync
+gnome_keyring_item_set_attributes
+gnome_keyring_item_set_attributes_sync
+gnome_keyring_item_get_acl
+gnome_keyring_item_get_acl_sync
+gnome_keyring_item_set_acl
+gnome_keyring_item_set_acl_sync
+gnome_keyring_item_info_free
+gnome_keyring_item_info_new
+gnome_keyring_item_info_copy
+gnome_keyring_item_info_get_type
+gnome_keyring_item_info_set_type
+gnome_keyring_item_info_get_secret
+gnome_keyring_item_info_set_secret
+gnome_keyring_item_info_get_display_name
+gnome_keyring_item_info_set_display_name
+gnome_keyring_item_info_get_mtime
+gnome_keyring_item_info_get_ctime
+gnome_keyring_application_ref_new
+gnome_keyring_application_ref_copy
+gnome_keyring_application_ref_free
+gnome_keyring_access_control_new
+gnome_keyring_access_control_copy
+gnome_keyring_access_control_free
+gnome_keyring_acl_copy
+gnome_keyring_acl_free
+gnome_keyring_item_ac_get_display_name
+gnome_keyring_item_ac_set_display_name
+gnome_keyring_item_ac_get_path_name
+gnome_keyring_item_ac_set_path_name
+gnome_keyring_item_ac_get_access_type
+gnome_keyring_item_ac_set_access_type
+GnomeKeyringNetworkPasswordData
+gnome_keyring_network_password_free
+gnome_keyring_network_password_list_free
+gnome_keyring_find_network_password
+gnome_keyring_find_network_password_sync
+gnome_keyring_set_network_password
+gnome_keyring_set_network_password_sync
+</SECTION>
+