Reference documentation

.gitignore

@@ -1,12 +1,13 @@
 *~
-*.o
+*.bak
-*.la
-*.lo
-*.pyc
 *.gcov
 *.gcno
 *.gcda
 *.gir
+*.la
+*.lo
+*.o
+*.pyc
 *.pc
 *.tar.gz
 *.typelib
@@ -22,6 +23,7 @@ config.*
 depcomp
 install-sh
 INSTALL
+gtk-doc.make
 libtool
 ltmain.sh
 Makefile
@@ -29,6 +31,7 @@ Makefile.in
 Makefile.in.in
 missing
 stamp*
+*.stamp
 .settings
 .project
 .cproject
@@ -37,6 +40,21 @@ stamp*
 /build/m4
 /build/valgrind-suppressions
 
+/docs/reference/libsecret/version.xml
+/docs/reference/libsecret/libsecret-decl-list.txt
+/docs/reference/libsecret/libsecret-decl.txt
+/docs/reference/libsecret/libsecret-scan.c
+/docs/reference/libsecret/html
+/docs/reference/libsecret/libsecret-undeclared.txt
+/docs/reference/libsecret/libsecret-undocumented.txt
+/docs/reference/libsecret/libsecret-unused.txt
+/docs/reference/libsecret/libsecret.args
+/docs/reference/libsecret/libsecret.hierarchy
+/docs/reference/libsecret/libsecret.prerequisites
+/docs/reference/libsecret/libsecret.signals
+/docs/reference/libsecret/tmpl
+/docs/reference/libsecret/xml
+
 /po/POTFILES
 /po/libsecret.pot
 

Makefile.am

@@ -3,7 +3,7 @@ include $(top_srcdir)/Makefile.decl
 
 ACLOCAL_AMFLAGS = -I build/m4 ${ACLOCAL_FLAGS}
 
-SUBDIRS = build po egg library
+SUBDIRS = build egg library po docs
 
 DISTCHECK_CONFIGURE_FLAGS = \
 	--enable-debug=yes \

autogen.sh

@@ -91,6 +91,8 @@ $ACLOCAL $ACLOCAL_FLAGS || exit $?
 libtoolize --force || exit $?
 intltoolize --force --copy || exit $?
 
+gtkdocize || exit $?
+
 autoheader || exit $?
 
 $AUTOMAKE --add-missing || exit $?

configure.ac

@@ -66,6 +66,8 @@ PKG_CHECK_MODULES(GLIB,
 LIBS="$LIBS $GLIB_LIBS"
 CFLAGS="$CFLAGS $GLIB_CFLAGS"
 
+GTK_DOC_CHECK(1.9)
+
 GOBJECT_INTROSPECTION_CHECK([1.29])
 AC_PATH_PROG(GLIB_MKENUMS, glib-mkenums)
 
@@ -225,6 +227,10 @@ AC_SUBST(SECRET_MINOR)
 AC_CONFIG_FILES([
 	Makefile
 	build/Makefile
+	docs/Makefile
+	docs/reference/Makefile
+	docs/reference/libsecret/Makefile
+	docs/reference/libsecret/version.xml
 	egg/Makefile
 	egg/tests/Makefile
 	po/Makefile.in

docs/Makefile.am

@@ -0,0 +1,2 @@
+
+SUBDIRS = reference

docs/reference/COPYING

@@ -0,0 +1,30 @@
+This work may be reproduced and distributed in whole or in part, in
+any medium, physical or electronic, so as long as this copyright
+notice remains intact and unchanged on all copies.  Commercial
+redistribution is permitted and encouraged, but you may not
+redistribute, in whole or in part, under terms more restrictive than
+those under which you received it. If you redistribute a modified or
+translated version of this work, you must also make the source code to
+the modified or translated version available in electronic form
+without charge.  However, mere aggregation as part of a larger work
+shall not count as a modification for this purpose.
+
+All code examples in this work are placed into the public domain,
+and may be used, modified and redistributed without restriction.
+
+BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY REPAIR OR CORRECTION.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.

docs/reference/Makefile.am

@@ -0,0 +1,2 @@
+
+SUBDIRS = libsecret

docs/reference/libsecret/Makefile.am

@@ -0,0 +1,102 @@
+## 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 the module, e.g. 'glib'.
+DOC_MODULE=libsecret
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+DOC_MODULE_VERSION=@SECRET_MAJOR@
+
+# 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=$(top_srcdir)/library
+
+# 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=--deprecated-guards="SECRET_DISABLE_DEPRECATED"
+
+# 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-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=
+
+# 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)/library/*.h
+CFILE_GLOB=$(top_srcdir)/library/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=
+
+# Header files to ignore when scanning. Use base file name, no paths
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES= \
+	mock-service.h \
+	secret-dbus-generated.h \
+	secret-private.h \
+	$(NULL)
+
+# 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=
+
+# 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. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS= -I$(top_srcdir) -I$(top_builddir) $(GLIB_CFLAGS) -Wno-error
+GTKDOC_LIBS= $(GLIB_LIBS) $(GOBJECT_LIBS) \
+	$(top_builddir)/library/libsecret-@SECRET_MAJOR@.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 +=
+
+# 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 = tmpl/secret-unused.sgml
+
+# Comment this out if you want your docs-status tested during 'make check'
+#TESTS_ENVIRONMENT = cd $(srcsrc)
+#TESTS = $(GTKDOC_CHECK)

docs/reference/libsecret/libsecret-docs.sgml

@@ -0,0 +1,34 @@
+<?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" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+	<bookinfo>
+		<title>Libsecret Library Reference Manual</title>
+		<releaseinfo>
+			for libsecret &version;.
+			An online version of this documentation can be found at
+			<ulink role="online-location" url="http://developer.gnome.org/libsecret/stable/">http://developer.gnome.org/libsecret/stable/</ulink>.
+		</releaseinfo>
+	</bookinfo>
+
+	<part id="simple">
+		<title>Simple API</title>
+		<xi:include href="xml/secret-password.xml"/>
+	</part>
+
+	<part id="complete">
+		<title>Complete API</title>
+		<xi:include href="xml/secret-service.xml"/>
+		<xi:include href="xml/secret-collection.xml"/>
+		<xi:include href="xml/secret-item.xml"/>
+		<xi:include href="xml/secret-value.xml"/>
+		<xi:include href="xml/secret-prompt.xml"/>
+		<xi:include href="xml/secret-error.xml"/>
+	</part>
+
+	<xi:include href="xml/annotation-glossary.xml">
+		<xi:fallback />
+	</xi:include>
+</book>

docs/reference/libsecret/libsecret-overrides.txt

@@ -0,0 +1,2 @@
+# These are manually-edited to override or add declarations to those scanned
+# from the header files.

docs/reference/libsecret/libsecret-sections.txt

@@ -0,0 +1,252 @@
+<SECTION>
+<FILE>secret-collection</FILE>
+SecretCollection
+SecretCollectionClass
+secret_collection_new
+secret_collection_new_finish
+secret_collection_new_sync
+secret_collection_create
+secret_collection_create_finish
+secret_collection_create_sync
+secret_collection_delete
+secret_collection_delete_finish
+secret_collection_delete_sync
+secret_collection_get_created
+secret_collection_get_items
+secret_collection_get_label
+secret_collection_set_label
+secret_collection_set_label_finish
+secret_collection_set_label_sync
+secret_collection_get_locked
+secret_collection_get_modified
+secret_collection_refresh
+<SUBSECTION Standard>
+SECRET_COLLECTION
+SECRET_COLLECTION_CLASS
+SECRET_COLLECTION_GET_CLASS
+SECRET_IS_COLLECTION
+SECRET_IS_COLLECTION_CLASS
+SECRET_TYPE_COLLECTION
+SecretCollectionPrivate
+secret_collection_get_type
+</SECTION>
+
+<SECTION>
+<FILE>secret-item</FILE>
+SecretItem
+SecretItemClass
+secret_item_new
+secret_item_new_finish
+secret_item_new_sync
+secret_item_create
+secret_item_create_finish
+secret_item_create_sync
+secret_item_delete
+secret_item_delete_finish
+secret_item_delete_sync
+secret_item_get_attributes
+secret_item_set_attributes
+secret_item_set_attributes_finish
+secret_item_set_attributes_sync
+secret_item_get_created
+secret_item_get_label
+secret_item_set_label
+secret_item_set_label_finish
+secret_item_set_label_sync
+secret_item_get_locked
+secret_item_get_modified
+secret_item_get_schema
+secret_item_get_secret
+secret_item_get_secret_finish
+secret_item_get_secret_sync
+secret_item_set_secret
+secret_item_set_secret_finish
+secret_item_set_secret_sync
+secret_item_refresh
+<SUBSECTION Standard>
+SECRET_IS_ITEM
+SECRET_IS_ITEM_CLASS
+SECRET_ITEM
+SECRET_ITEM_CLASS
+SECRET_ITEM_GET_CLASS
+SECRET_TYPE_ITEM
+SecretItemPrivate
+secret_item_get_type
+</SECTION>
+
+<SECTION>
+<FILE>secret-error</FILE>
+SECRET_ERROR
+SecretError
+<SUBSECTION Standard>
+SECRET_TYPE_ERROR
+secret_error_get_quark
+secret_error_get_type
+</SECTION>
+
+<SECTION>
+<FILE>secret-password</FILE>
+SecretSchema
+SecretSchemaType
+secret_password_store
+secret_password_storev
+secret_password_store_finish
+secret_password_store_sync
+secret_password_storev_sync
+secret_password_lookup
+secret_password_lookupv
+secret_password_lookup_finish
+secret_password_lookup_sync
+secret_password_lookupv_sync
+secret_password_remove
+secret_password_removev
+secret_password_remove_finish
+secret_password_remove_sync
+secret_password_removev_sync
+secret_password_free
+<SUBSECTION Standard>
+SECRET_TYPE_SCHEMA_TYPE
+secret_schema_type_get_type
+</SECTION>
+
+<SECTION>
+<FILE>secret-prompt</FILE>
+SecretPrompt
+SecretPromptClass
+secret_prompt_get_result_value
+secret_prompt_perform
+secret_prompt_perform_finish
+secret_prompt_perform_sync
+secret_prompt_run
+<SUBSECTION Standard>
+SECRET_IS_PROMPT
+SECRET_IS_PROMPT_CLASS
+SECRET_PROMPT
+SECRET_PROMPT_CLASS
+SECRET_PROMPT_GET_CLASS
+SECRET_TYPE_PROMPT
+SecretPromptPrivate
+secret_prompt_get_type
+</SECTION>
+
+<SECTION>
+<FILE>secret-service</FILE>
+SecretService
+SecretServiceClass
+SecretServiceFlags
+secret_service_get
+secret_service_get_sync
+secret_service_get_finish
+secret_service_new
+secret_service_new_finish
+secret_service_new_sync
+secret_service_get_collections
+secret_service_get_flags
+secret_service_get_session_algorithms
+secret_service_get_session_path
+secret_service_ensure_session
+secret_service_ensure_session_finish
+secret_service_ensure_session_sync
+secret_service_ensure_collections
+secret_service_ensure_collections_finish
+secret_service_ensure_collections_sync
+secret_service_search
+secret_service_search_finish
+secret_service_search_sync
+secret_service_search_for_paths
+secret_service_search_for_paths_finish
+secret_service_search_for_paths_sync
+secret_service_get_secrets
+secret_service_get_secrets_finish
+secret_service_get_secrets_sync
+secret_service_get_secrets_for_paths
+secret_service_get_secrets_for_paths_finish
+secret_service_get_secrets_for_paths_sync
+secret_service_get_secret_for_path
+secret_service_get_secret_for_path_finish
+secret_service_get_secret_for_path_sync
+secret_service_lock
+secret_service_lock_finish
+secret_service_lock_sync
+secret_service_lock_paths
+secret_service_lock_paths_finish
+secret_service_lock_paths_sync
+secret_service_unlock
+secret_service_unlock_finish
+secret_service_unlock_sync
+secret_service_unlock_paths
+secret_service_unlock_paths_finish
+secret_service_unlock_paths_sync
+secret_service_store
+secret_service_storev
+secret_service_store_finish
+secret_service_store_sync
+secret_service_storev_sync
+secret_service_lookup
+secret_service_lookupv
+secret_service_lookup_finish
+secret_service_lookup_sync
+secret_service_lookupv_sync
+secret_service_remove
+secret_service_removev
+secret_service_remove_finish
+secret_service_remove_sync
+secret_service_removev_sync
+secret_service_prompt
+secret_service_prompt_finish
+secret_service_prompt_sync
+secret_service_create_collection_path
+secret_service_create_collection_path_finish
+secret_service_create_collection_path_sync
+secret_service_create_item_path
+secret_service_create_item_path_finish
+secret_service_create_item_path_sync
+secret_service_delete_path
+secret_service_delete_path_finish
+secret_service_delete_path_sync
+<SUBSECTION Standard>
+SECRET_IS_SERVICE
+SECRET_IS_SERVICE_CLASS
+SECRET_SERVICE
+SECRET_SERVICE_CLASS
+SECRET_SERVICE_GET_CLASS
+SECRET_TYPE_SERVICE
+SECRET_TYPE_SERVICE_FLAGS
+SecretServicePrivate
+secret_service_flags_get_type
+secret_service_get_type
+</SECTION>
+
+<SECTION>
+<FILE>secret-value</FILE>
+SecretValue
+secret_value_new
+secret_value_new_full
+secret_value_get
+secret_value_get_content_type
+secret_value_ref
+secret_value_unref
+<SUBSECTION Standard>
+SECRET_TYPE_VALUE
+secret_value_get_type
+</SECTION>
+
+<SECTION>
+<FILE>SecretGenService</FILE>
+</SECTION>
+
+<SECTION>
+<FILE>SecretGenCollection</FILE>
+</SECTION>
+
+<SECTION>
+<FILE>SecretGenItem</FILE>
+</SECTION>
+
+<SECTION>
+<FILE>SecretGenSession</FILE>
+</SECTION>
+
+<SECTION>
+<FILE>SecretGenPrompt</FILE>
+</SECTION>

docs/reference/libsecret/libsecret.interfaces

@@ -0,0 +1,6 @@
+GDBusProxy GDBusInterface GInitable GAsyncInitable
+SecretCollection GDBusInterface GInitable GAsyncInitable
+SecretItem GDBusInterface GInitable GAsyncInitable
+SecretPrompt GDBusInterface GInitable GAsyncInitable
+SecretService GDBusInterface GInitable GAsyncInitable
+GDBusConnection GInitable GAsyncInitable

docs/reference/libsecret/libsecret.types

@@ -0,0 +1,7 @@
+secret_collection_get_type
+secret_error_get_type
+secret_item_get_type
+secret_prompt_get_type
+secret_value_get_type
+secret_service_flags_get_type
+secret_service_get_type

docs/reference/libsecret/version.xml.in

@@ -0,0 +1 @@
+@VERSION@

library/Makefile.am

@@ -79,7 +79,7 @@ secret-dbus-generated.c: $(DBUS_XML_DEFINITIONS) Makefile.am
 	$(AM_V_GEN) gdbus-codegen --interface-prefix org.freedesktop.Secret. \
 		--generate-c-code secret-dbus-generated --c-namespace SecretGen \
 		$(DBUS_XML_DEFINITIONS)
-	$(AM_V_GEN) sed -i -e 's/secret_gen_/_secret_gen_/g' secret-dbus-generated.[ch]
+	$(AM_V_GEN) sed -i -e 's/secret_gen_/_secret_gen_/g' -e 's/type-/type/g' secret-dbus-generated.[ch]
 	$(AM_V_GEN) sed -i -e '1i #define GLIB_DISABLE_DEPRECATION_WARNINGS' secret-dbus-generated.c
 secret-dbus-generated.h: secret-dbus-generated.c
 

library/secret-collection.c

@@ -21,6 +21,35 @@
 
 #include <glib/gi18n-lib.h>
 
+/**
+ * SECTION:secret-collection
+ * @title: SecretCollection
+ * @short_description: A collection of secret items
+ *
+ * #SecretCollection represents a collection of secret items stored in the
+ * Secret Service.
+ *
+ * A collection can be in a locked or unlocked state. Use secret_service_lock()
+ * or secret_service_unlock() to lock or unlock the collection.
+ *
+ * Use the SecretCollection::items property or secret_service_get_items() to
+ * lookup the items in the collection. There may not be any items exposed when
+ * the collection is locked.
+ */
+
+/**
+ * SecretCollection:
+ *
+ * A proxy object representing a collection of secrets in the Secret Service.
+ */
+
+/**
+ * SecretCollectionClass:
+ * @parent_class: the parent class
+ *
+ * The class for #SecretCollection.
+ */
+
 enum {
 	PROP_0,
 	PROP_SERVICE,
@@ -412,26 +441,67 @@ secret_collection_class_init (SecretCollectionClass *klass)
 
 	proxy_class->g_properties_changed = secret_collection_properties_changed;
 
+	/**
+	 * SecretCollection:service:
+	 *
+	 * The #SecretService object that this collection is associated with and
+	 * uses to interact with the actual DBus Secret Service.
+	 */
 	g_object_class_install_property (gobject_class, PROP_SERVICE,
 	            g_param_spec_object ("service", "Service", "Secret Service",
 	                                 SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretCollection:items:
+	 *
+	 * A list of #SecretItem objects representing the items that are in
+	 * this collection. This list will be empty if the collection is locked.
+	 */
 	g_object_class_install_property (gobject_class, PROP_ITEMS,
 	             g_param_spec_boxed ("items", "Items", "Items in collection",
 	                                 _secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretCollection:label:
+	 *
+	 * The human readable label for the collection.
+	 *
+	 * Setting this property will result in the label of the collection being
+	 * set asynchronously. To properly track the changing of the label use the
+	 * secret_collection_set_label() function.
+	 */
 	g_object_class_install_property (gobject_class, PROP_LABEL,
 	            g_param_spec_string ("label", "Label", "Item label",
 	                                 NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretCollection:locked:
+	 *
+	 * Whether the collection is locked or not.
+	 *
+	 * To lock or unlock a collection use the secret_service_lock() or
+	 * secret_service_unlock() functions.
+	 */
 	g_object_class_install_property (gobject_class, PROP_LOCKED,
 	           g_param_spec_boolean ("locked", "Locked", "Item locked",
 	                                 TRUE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretCollection:created:
+	 *
+	 * The date and time (in seconds since the UNIX epoch) that this
+	 * collection was created.
+	 */
 	g_object_class_install_property (gobject_class, PROP_CREATED,
 	            g_param_spec_uint64 ("created", "Created", "Item creation date",
 	                                 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretCollection:modified:
+	 *
+	 * The date and time (in seconds since the UNIX epoch) that this
+	 * collection was last modified.
+	 */
 	g_object_class_install_property (gobject_class, PROP_MODIFIED,
 	            g_param_spec_uint64 ("modified", "Modified", "Item modified date",
 	                                 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
@@ -1152,6 +1222,9 @@ secret_collection_set_label_sync (SecretCollection *self,
  *
  * Get whether the collection is locked or not.
  *
+ * Use secret_service_lock() or secret_service_unlock() to lock or unlock the
+ * collection.
+ *
  * Returns: whether the collection is locked or not
  */
 gboolean

library/secret-collection.h

@@ -35,11 +35,15 @@ typedef struct _SecretCollectionPrivate SecretCollectionPrivate;
 
 struct _SecretCollection {
 	GDBusProxy parent;
+
+	/*< private >*/
 	SecretCollectionPrivate *pv;
 };
 
 struct _SecretCollectionClass {
 	GDBusProxyClass parent_class;
+
+	/*< private >*/
 	gpointer padding[8];
 };
 

library/secret-item.c

@@ -22,6 +22,44 @@
 
 #include <glib/gi18n-lib.h>
 
+/**
+ * SECTION:secret-item
+ * @title: SecretItem
+ * @short_description: A secret item
+ *
+ * #SecretItem represents a secret item stored in the Secret Service.
+ *
+ * Each item has a value, represented by a #SecretValue, which can be
+ * retrieved by secret_service_get_secret() or set by secret_service_set_secret().
+ * The item is only available when the item is not locked.
+ *
+ * Items can be locked or unlocked using the secret_service_lock() or
+ * secret_service_unlock() functions. The Secret Service may not be able to
+ * unlock individual items, and may unlock an entire collection when a single
+ * item is unlocked.
+ *
+ * Each item has a set of attributes, which are used to locate the item later.
+ * These are not stored or transferred in a secure manner. Each attribute has
+ * a string name and a string value. Use secret_service_search() to search for
+ * items based on their attributes, and secret_item_set_attributes to change
+ * the attributes associated with an item.
+ *
+ * Items can be created with secret_item_create() or secret_service_store().
+ */
+
+/**
+ * SecretItem:
+ *
+ * A proxy object representing a secret item in the Secret Service.
+ */
+
+/**
+ * SecretItemClass:
+ * @parent_class: the parent class
+ *
+ * The class for #SecretItem.
+ */
+
 enum {
 	PROP_0,
 	PROP_SERVICE,
@@ -240,30 +278,81 @@ secret_item_class_init (SecretItemClass *klass)
 
 	proxy_class->g_properties_changed = secret_item_properties_changed;
 
+	/**
+	 * SecretItem:service:
+	 *
+	 * The #SecretService object that this item is associated with and
+	 * uses to interact with the actual DBus Secret Service.
+	 */
 	g_object_class_install_property (gobject_class, PROP_SERVICE,
 	            g_param_spec_object ("service", "Service", "Secret Service",
 	                                 SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretItem:attributes:
+	 *
+	 * The attributes set on this item. Attributes are used to locate an
+	 * item. They are not guaranteed to be stored or transferred securely.
+	 *
+	 * The schema describes which attributes should be present and their types.
+	 */
 	g_object_class_install_property (gobject_class, PROP_ATTRIBUTES,
 	             g_param_spec_boxed ("attributes", "Attributes", "Item attributes",
 	                                 G_TYPE_HASH_TABLE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretItem:label:
+	 *
+	 * The human readable label for the item.
+	 *
+	 * Setting this property will result in the label of the item being
+	 * set asynchronously. To properly track the changing of the label use the
+	 * secret_item_set_label() function.
+	 */
 	g_object_class_install_property (gobject_class, PROP_LABEL,
 	            g_param_spec_string ("label", "Label", "Item label",
 	                                 NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretItem:schema:
+	 *
+	 * The schema for this item. This is a dotted string that describes
+	 * which attributes should be present and the types of values on
+	 * those attributes.
+	 */
 	g_object_class_install_property (gobject_class, PROP_SCHEMA,
 	            g_param_spec_string ("schema", "Schema", "Item schema",
 	                                 NULL, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretItem:locked:
+	 *
+	 * Whether the item is locked or not. An item may not be independently
+	 * lockable separate from other items in its collection.
+	 *
+	 * To lock or unlock a item use the secret_service_lock() or
+	 * secret_service_unlock() functions.
+	 */
 	g_object_class_install_property (gobject_class, PROP_LOCKED,
 	           g_param_spec_boolean ("locked", "Locked", "Item locked",
 	                                 TRUE, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretItem:created:
+	 *
+	 * The date and time (in seconds since the UNIX epoch) that this
+	 * item was created.
+	 */
 	g_object_class_install_property (gobject_class, PROP_CREATED,
 	            g_param_spec_uint64 ("created", "Created", "Item creation date",
 	                                 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretItem:modified:
+	 *
+	 * The date and time (in seconds since the UNIX epoch) that this
+	 * item was last modified.
+	 */
 	g_object_class_install_property (gobject_class, PROP_MODIFIED,
 	            g_param_spec_uint64 ("modified", "Modified", "Item modified date",
 	                                 0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
@@ -590,6 +679,7 @@ item_properties_new (const gchar *schema_name,
  * @attributes: attributes for the new item
  * @value: secret value for the new item
  * @replace: whether to replace an existing item with the same attributes
+ * @cancellable: optional cancellation object
  * @callback: called when the operation completes
  * @user_data: data to pass to the callback
  *

library/secret-item.h

@@ -37,11 +37,15 @@ typedef struct _SecretItemPrivate   SecretItemPrivate;
 
 struct _SecretItem {
 	GDBusProxy parent_instance;
+
+	/*< private >*/
 	SecretItemPrivate *pv;
 };
 
 struct _SecretItemClass {
 	GDBusProxyClass parent_class;
+
+	/*< private >*/
 	gpointer padding[4];
 };
 

library/secret-methods.c

@@ -758,7 +758,7 @@ secret_service_get_secrets_for_paths (SecretService *self,
  * Items that are locked will not be included the results.
  *
  * Returns: (transfer full): a newly allocated hash table of item_path keys to
- *          #GSecretValue values.
+ *          #SecretValue values.
  */
 GHashTable *
 secret_service_get_secrets_for_paths_finish (SecretService *self,
@@ -796,7 +796,7 @@ secret_service_get_secrets_for_paths_finish (SecretService *self,
  * Items that are locked will not be included the results.
  *
  * Returns: (transfer full): a newly allocated hash table of item_path keys to
- *          #GSecretValue values.
+ *          #SecretValue values.
  */
 GHashTable *
 secret_service_get_secrets_for_paths_sync (SecretService *self,
@@ -894,8 +894,8 @@ secret_service_get_secrets (SecretService *self,
  *
  * Items that are locked will not be included the results.
  *
- * Returns: (transfer full): a newly allocated hash table of #GSecretItem keys
+ * Returns: (transfer full): a newly allocated hash table of #SecretItem keys
- *          to #GSecretValue values.
+ *          to #SecretValue values.
  */
 GHashTable *
 secret_service_get_secrets_finish (SecretService *self,
@@ -953,8 +953,8 @@ secret_service_get_secrets_finish (SecretService *self,
  *
  * Items that are locked will not be included the results.
  *
- * Returns: (transfer full): a newly allocated hash table of #GSecretItem keys
+ * Returns: (transfer full): a newly allocated hash table of #SecretItem keys
- *          to #GSecretValue values.
+ *          to #SecretValue values.
  */
 GHashTable *
 secret_service_get_secrets_sync (SecretService *self,

library/secret-password.c

@@ -18,6 +18,60 @@
 
 #include <egg/egg-secure-memory.h>
 
+/**
+ * SECTION:secret-password
+ * @title: Password storage
+ * @short_description: Simple password storage and lookup
+ *
+ * This is a simple API for storing passwords and retrieving passwords in the
+ * Secret Service.
+ *
+ * Each password is associated with a set of attributes. Attribute values can
+ * be either strings, integers or booleans.
+ *
+ * The names and types of allowed attributes for a given password are defined
+ * with a schema. Certain schemas are predefined. Additional schemas can be
+ * defined via the %SecretSchema structure.
+ *
+ * Each of the functions accept a variable list of attributes names and their
+ * values. Include a %NULL to terminate the list of attributes.
+ */
+
+/**
+ * SecretSchema:
+ * @schema_name: the dotted name of the schema
+ * @attributes: the attribute names and types of those attributes
+ *
+ * Represents a set of attributes that are stored with an item. These schemas
+ * are used for interoperability between various services storing the same types
+ * of items.
+ *
+ * Each schema has a name like "org.gnome.keyring.NetworkPassword", and defines
+ * a set of attributes, and types (string, integer, boolean) for those attributes.
+ *
+ * Attributes are stored as strings in the Secret Service, and the attribute
+ * types simply define standard ways to store integer and boolean values as strings.
+ */
+
+/**
+ * SecretSchemaAttribute:
+ * @name: name of the attribute
+ * @type: the type of the attribute
+ *
+ * An attribute in a #SecretSchema.
+ */
+
+/**
+ * SecretSchemaType:
+ * @SECRET_ATTRIBUTE_BOOLEAN: a boolean attribute, stored as 'true' or 'false'
+ * @SECRET_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal
+ * @SECRET_ATTRIBUTE_STRING: a utf-8 string attribute
+ *
+ * The type of an attribute in a #SecretSchema. Attributes are stored as strings
+ * in the Secret Service, and the attribute types simply define standard ways
+ * to store integer and boolean values as strings.
+ */
+
 typedef struct {
 	const SecretSchema *schema;
 	GHashTable *attributes;

library/secret-prompt.c

@@ -19,7 +19,37 @@
 #include <glib.h>
 #include <glib/gi18n-lib.h>
 
-#include <gcrypt.h>
+/**
+ * SECTION:secret-prompt
+ * @title: SecretPrompt
+ * @short_description: a prompt in the Service
+ *
+ * A #SecretPrompt represents a prompt in the Secret Service.
+ *
+ * Certain actions on the Secret Service require user prompting to complete,
+ * such as creating a collection, or unlocking a collection. When such a prompt
+ * is necessary, then a #SecretPrompt object is created by this library, and
+ * passed to the secret_service_prompt_async() method. In this way it is handled
+ * automatically.
+ *
+ * In order to customize prompt handling, override the
+ * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish
+ * virtual methods of the #SecretService class.
+ */
+
+/**
+ * SecretPrompt:
+ *
+ * A proxy object representing a prompt that the Secret Service will display
+ * to the user.
+ */
+
+/**
+ * SecretPromptClass:
+ * @parent_class: the parent class
+ *
+ * The class for #SecretPrompt.
+ */
 
 typedef struct _SecretPromptPrivate {
 	/* Locked by mutex */

library/secret-prompt.h

@@ -35,11 +35,15 @@ typedef struct _SecretPromptPrivate SecretPromptPrivate;
 
 struct _SecretPrompt {
 	GDBusProxy parent_instance;
+
+	/*< private >*/
 	SecretPromptPrivate *pv;
 };
 
 struct _SecretPromptClass {
 	GDBusProxyClass parent_class;
+
+	/*< private >*/
 	gpointer padding[8];
 };
 

library/secret-service.c

@@ -24,6 +24,79 @@
 
 #include "egg/egg-secure-memory.h"
 
+/**
+ * SECTION:secret-service
+ * @title: SecretService
+ * @short_description: the Secret Service
+ *
+ * A #SecretService object represents the Secret Service implementation which
+ * runs as a DBus service.
+ *
+ * Normally a single #SecretService object can be shared between multiple
+ * callers. The secret_service_get() method is used to access this #SecretService
+ * object. If a new independent #SecretService object is required, use
+ * secret_service_new().
+ *
+ * In order to securely transfer secrets to the Sercret Service, an session
+ * is established. This session can be established while initializing a
+ * #SecretService object by passing the %SECRET_SERVICE_OPEN_SESSION flag
+ * to the secret_service_get() or secret_service_new() functions. In order to
+ * establish a session on an already existing #SecretService, use the
+ * secret_service_ensure_session() function.
+ *
+ * To search for items, use the secret_service_search() method.
+ *
+ * Multiple collections can exist in the Secret Service, each of which contains
+ * secret items. In order to instantiate #SecretCollection objects which
+ * represent those collections while initializing a #SecretService then pass
+ * the %SECRET_SERVICE_LOAD_COLLECTIONS flag to the secret_service_get() or
+ * secret_service_new() functions. In order to establish a session on an already
+ * existing #SecretService, use the secret_service_ensure_collections() function.
+ * To access the list of collections use secret_service_get_collections().
+ *
+ * Certain actions on the Secret Service require user prompting to complete,
+ * such as creating a collection, or unlocking a collection. When such a prompt
+ * is necessary, then a #SecretPrompt object is created by this library, and
+ * passed to the secret_service_prompt_async() method. In this way it is handled
+ * automatically.
+ *
+ * In order to customize prompt handling, override the
+ * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish
+ * virtual methods of the #SecretService class.
+ */
+
+/**
+ * SecretService:
+ *
+ * A proxy object representing the Secret Service.
+ */
+
+/**
+ * SecretServiceClass:
+ * @parent_class: the parent class
+ * @collection_gtype: the #GType of the #SecretCollection objects instantiated
+ *                    by the #SecretService proxy
+ * @item_gtype: the #GType of the #SecretItem objects instantiated by the
+ *              #SecretService proxy
+ * @prompt_async: called to perform asynchronous prompting when necessary
+ * @prompt_finish: called to complete an asynchronous prompt operation
+ * @prompt_sync: called to perform synchronous prompting when necessary
+ *
+ * The class for #SecretService.
+ */
+
+/**
+ * SecretServiceFlags:
+ * @SECRET_SERVICE_NONE: no flags for initializing the #SecretService
+ * @SECRET_SERVICE_OPEN_SESSION: establish a session for transfer of secrets
+ *                               while initializing the #SecretService
+ * @SECRET_SERVICE_LOAD_COLLECTIONS: load collections while initializing the
+ *                                   #SecretService
+ *
+ * Flags which determine which parts of the #SecretService proxy are initialized
+ * during a secret_service_get() or secret_service_new() operation.
+ */
+
 EGG_SECURE_GLIB_DEFINITIONS ();
 
 static const gchar *default_bus_name = SECRET_SERVICE_BUS_NAME;
@@ -249,11 +322,29 @@ secret_service_class_init (SecretServiceClass *klass)
 	klass->item_gtype = SECRET_TYPE_ITEM;
 	klass->collection_gtype = SECRET_TYPE_COLLECTION;
 
+	/**
+	 * SecretService:flags:
+	 *
+	 * A set of flags describing which parts of the secret service have
+	 * been initialized.
+	 */
 	g_object_class_install_property (object_class, PROP_FLAGS,
 	             g_param_spec_flags ("flags", "Flags", "Service flags",
 	                                 secret_service_flags_get_type (), SECRET_SERVICE_NONE,
 	                                 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 
+	/**
+	 * SecretService:collections:
+	 *
+	 * A list of #SecretCollection objects representing the collections in
+	 * the Secret Service. This list may be %NULL if the collections have
+	 * not been loaded.
+	 *
+	 * To load the collections, specify the %SECRET_SERVICE_LOAD_COLLECTIONS
+	 * initialization flag when calling the secret_service_get() or
+	 * secret_service_new() functions. Or call the secret_service_ensure_collections()
+	 * method.
+	 */
 	g_object_class_install_property (object_class, PROP_COLLECTIONS,
 	             g_param_spec_boxed ("collections", "Collections", "Secret Service Collections",
 	                                 _secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
@@ -1319,7 +1410,7 @@ secret_service_ensure_collections_sync (SecretService *self,
  * This function is called by other parts of this library to handle prompts
  * for the various actions that can require prompting.
  *
- * Override the #SecretService <literal>prompt_sync()</literal> virtual method
+ * Override the #SecretServiceClass::prompt_sync() virtual method
  * to change the behavior of the propmting. The default behavior is to simply
  * run secret_prompt_perform_sync() on the prompt.
  *

library/secret-service.h

@@ -44,6 +44,8 @@ typedef struct _SecretServicePrivate SecretServicePrivate;
 
 struct _SecretService {
 	GDBusProxy parent;
+
+	/*< private >*/
 	SecretServicePrivate *pv;
 };
 
@@ -68,6 +70,7 @@ struct _SecretServiceClass {
 	                                  GAsyncResult *result,
 	                                  GError **error);
 
+	/*< private >*/
 	gpointer padding[16];
 };
 

library/secret-types.h

@@ -36,11 +36,13 @@ typedef enum {
 } SecretSchemaType;
 
 typedef struct {
-	const gchar *schema_name;
-	struct {
 	const gchar* name;
 	SecretSchemaType type;
-	} attributes[32];
+} SecretSchemaAttribute;
+
+typedef struct {
+	const gchar *schema_name;
+	SecretSchemaAttribute attributes[32];
 
 	/* <private> */
 	gpointer reserved1;

library/secret-util.c

@@ -17,6 +17,15 @@
 
 #include <string.h>
 
+/**
+ * SecretError:
+ * @SECRET_ERROR_PROTOCOL: received an invalid data or message from the Secret
+ *                         Service
+ *
+ * Errors returned by the Secret Service. None of the errors are appropriate
+ * for display to the user.
+ */
+
 static void
 list_unref_free (GList *reflist)
 {

library/secret-value.c

@@ -19,6 +19,30 @@
 
 #include <string.h>
 
+/**
+ * SECTION:secret-value
+ * @title: SecretValue
+ * @short_description: a value containing a secret
+ *
+ * A #SecretValue contains a password or other secret value.
+ *
+ * Use secret_value_get() to get the actual secret data, such as a password.
+ * The secret data is not necessarily null-terminated, unless the content type
+ * is "text/plain".
+ *
+ * Each #SecretValue has a content type. For passwords, this is "text/plain".
+ * Use secret_value_get_content_type() to look at the content type.
+ *
+ * #SecretValue is reference counted and immutable. The secret data is only
+ * freed when all references have been released via secret_value_unref().
+ */
+
+/**
+ * SecretValue:
+ *
+ * A secret value, like a password or other binary secret.
+ */
+
 EGG_SECURE_DECLARE (secret_value);
 
 struct _SecretValue {