soylent r243 - in trunk: . docs docs/reference docs/reference/libsoylent libsoylent m4
- From: svenp svn gnome org
- To: svn-commits-list gnome org
- Subject: soylent r243 - in trunk: . docs docs/reference docs/reference/libsoylent libsoylent m4
- Date: Sat, 26 Jul 2008 12:16:14 +0000 (UTC)
Author: svenp
Date: Sat Jul 26 12:16:14 2008
New Revision: 243
URL: http://svn.gnome.org/viewvc/soylent?rev=243&view=rev
Log:
added gtk-doc-tools support and basic infrastructure for the libsoylent documentation
Added:
trunk/docs/ (props changed)
trunk/docs/Makefile.am
trunk/docs/reference/ (props changed)
trunk/docs/reference/Makefile.am
trunk/docs/reference/libsoylent/ (props changed)
trunk/docs/reference/libsoylent/Makefile.am
trunk/docs/reference/libsoylent/libsoylent-docs.sgml
trunk/docs/reference/libsoylent/libsoylent-sections.txt
Modified:
trunk/ (props changed)
trunk/Makefile.am
trunk/configure.ac
trunk/libsoylent/sl-book.c
trunk/libsoylent/sl-entity.c
trunk/m4/ (props changed)
Modified: trunk/Makefile.am
==============================================================================
--- trunk/Makefile.am (original)
+++ trunk/Makefile.am Sat Jul 26 12:16:14 2008
@@ -4,7 +4,7 @@
SUBDIRS = src data
if ENABLE_LIBSOYLENT
-SUBDIRS += libsoylent
+SUBDIRS += libsoylent docs
endif
EXTRA_DIST =
@@ -30,3 +30,6 @@
fi
FORCE:
+
+# add generation of documentation to distcheck
+DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
Modified: trunk/configure.ac
==============================================================================
--- trunk/configure.ac (original)
+++ trunk/configure.ac Sat Jul 26 12:16:14 2008
@@ -27,6 +27,8 @@
AM_PROG_CC_C_O
+GTK_DOC_CHECK(1.9)
+
dnl Soylent-specific macros
AC_DEFUN([SOYLENT_RELEASE_CHECK],
@@ -174,6 +176,9 @@
src/Makefile
libsoylent/Makefile
libsoylent/test/Makefile
+ docs/Makefile
+ docs/reference/Makefile
+ docs/reference/libsoylent/Makefile
])
AC_OUTPUT
Added: trunk/docs/Makefile.am
==============================================================================
--- (empty file)
+++ trunk/docs/Makefile.am Sat Jul 26 12:16:14 2008
@@ -0,0 +1 @@
+SUBDIRS = reference
Added: trunk/docs/reference/Makefile.am
==============================================================================
--- (empty file)
+++ trunk/docs/reference/Makefile.am Sat Jul 26 12:16:14 2008
@@ -0,0 +1 @@
+SUBDIRS = libsoylent
Added: trunk/docs/reference/libsoylent/Makefile.am
==============================================================================
--- (empty file)
+++ trunk/docs/reference/libsoylent/Makefile.am Sat Jul 26 12:16:14 2008
@@ -0,0 +1,87 @@
+# 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=libsoylent
+
+# 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=../../../libsoylent
+
+# 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=--rebuild-types
+
+# 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)/libsoylent/*.h
+CFILE_GLOB=$(top_srcdir)/libsoylent/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=sl-priv-util.h test.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=
+
+# 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) $(LIBSOYLENT_CFLAGS)
+GTKDOC_LIBS = $(top_builddir)/libsoylent/libsoylent.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 +=
+
+# Comment this out if you want your docs-status tested during 'make check'
+#TESTS = $(GTKDOC_CHECK)
Added: trunk/docs/reference/libsoylent/libsoylent-docs.sgml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/libsoylent/libsoylent-docs.sgml Sat Jul 26 12:16:14 2008
@@ -0,0 +1,26 @@
+<?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>libsoylent Reference Manual</title>
+ <releaseinfo>
+ for libsoylent v0.2.0
+ The latest version of this documentation can be found on-line at
+ <ulink role="online-location" url="http://kalterregen.de/libsoylent/index.html">http://kalterregen.de/libsoylent</ulink>.
+ </releaseinfo>
+ </bookinfo>
+
+ <chapter>
+ <title>API documentation</title>
+ <xi:include href="xml/soylent.xml"/>
+ <xi:include href="xml/sl-book.xml"/>
+ <xi:include href="xml/sl-entity.xml"/>
+ <xi:include href="xml/sl-attribute.xml"/>
+ <xi:include href="xml/sl-person.xml"/>
+ <!--<xi:include href="xml/sl-group.xml"/>
+ <xi:include href="xml/sl-entity-handler.xml"/>
+ <xi:include href="xml/sl-entity-handler-file.xml"/>
+ <xi:include href="xml/sl-entity-handler-eds.xml"/>-->
+ </chapter>
+</book>
Added: trunk/docs/reference/libsoylent/libsoylent-sections.txt
==============================================================================
--- (empty file)
+++ trunk/docs/reference/libsoylent/libsoylent-sections.txt Sat Jul 26 12:16:14 2008
@@ -0,0 +1,205 @@
+<SECTION>
+<FILE>sl-person</FILE>
+SL_PERSON_TYPE
+<TITLE>SlPerson</TITLE>
+SlPerson
+SlPersonClass
+sl_person_new
+sl_person_constr
+<SUBSECTION Standard>
+SL_PERSON
+SL_IS_PERSON
+sl_person_get_type
+SL_PERSON_CLASS
+SL_IS_PERSON_CLASS
+SL_PERSON_GET_CLASS
+<SUBSECTION Private>
+SlPersonPriv
+</SECTION>
+
+<SECTION>
+<FILE>sl-group</FILE>
+SL_GROUP_TYPE
+SlGroupPriv
+<TITLE>SlGroup</TITLE>
+SlGroup
+SlGroupClass
+sl_group_new
+<SUBSECTION Standard>
+SL_GROUP
+SL_IS_GROUP
+sl_group_get_type
+SL_GROUP_CLASS
+SL_IS_GROUP_CLASS
+SL_GROUP_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>sl-attribute</FILE>
+<TITLE>Attributes and Attribute-Handlers</TITLE>
+SlAttribute
+SlAttributeClass
+sl_attribute_constr
+sl_attribute_new
+sl_attribute_set
+sl_attribute_get
+sl_attribute_set_at
+sl_attribute_get_at
+sl_attribute_remove_at
+sl_attribute_add
+sl_attribute_set_all
+sl_attribute_get_all
+sl_attribute_remove_all
+sl_attribute_get_name
+SlAttributeWriterFunc
+SlAttributeReaderFunc
+sl_attribute_writer_string
+sl_attribute_reader_string
+sl_attribute_writer_int
+sl_attribute_reader_int
+sl_entity_install_attribute_handler
+sl_entity_remove_attribute_handler
+<SUBSECTION Private>
+sl_attribute_handler_init
+sl_attribute_handler_cleanup
+sl_attribute_handler_write
+sl_attribute_handler_read
+SlAttributePriv
+SlAttributeHandler
+<SUBSECTION Standard>
+sl_attribute_get_type
+SL_ATTRIBUTE_TYPE
+SL_ATTRIBUTE
+SL_ATTRIBUTE_CLASS
+SL_IS_ATTRIBUTE
+SL_IS_ATTRIBUTE_CLASS
+SL_ATTRIBUTE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>sl-entity</FILE>
+<TITLE>SlEntity</TITLE>
+SL_ENTITY_TYPE
+SlEntityPriv
+SlEntity
+SlEntityClass
+sl_entity_constr
+sl_entity_constr_with_econtact
+sl_entity_set_ebook
+sl_entity_get_ebook
+sl_entity_get_econtact
+sl_entity_commit
+sl_entity_add_attribute
+sl_entity_remove_attribute
+sl_entity_get_attribute
+sl_entity_get_attributes
+sl_entity_set
+sl_entity_get
+sl_entity_remove
+sl_entity_set_at
+sl_entity_get_at
+sl_entity_remove_at
+sl_entity_set_values
+sl_entity_get_values
+sl_entity_remove_values
+<SUBSECTION Private>
+<SUBSECTION Standard>
+SL_ENTITY
+SL_IS_ENTITY
+sl_entity_get_type
+SL_ENTITY_CLASS
+SL_IS_ENTITY_CLASS
+SL_ENTITY_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>sl-entity-handler</FILE>
+SL_ENTITY_HANDLER_TYPE
+<TITLE>SlEntityHandler</TITLE>
+SlEntityHandler
+SlEntityHandlerClass
+sl_entity_handler_get
+sl_entity_handler_set
+<SUBSECTION Standard>
+SL_ENTITY_HANDLER
+SL_IS_ENTITY_HANDLER
+sl_entity_handler_get_type
+SL_ENTITY_HANDLER_CLASS
+SL_IS_ENTITY_HANDLER_CLASS
+SL_ENTITY_HANDLER_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>sl-entity-handler-file</FILE>
+SL_ENTITY_HANDLER_FILE_TYPE
+SlEntityHandlerFilePriv
+<TITLE>SlEntityHandlerFile</TITLE>
+SlEntityHandlerFile
+SlEntityHandlerFileClass
+sl_entity_handler_file_new
+sl_entity_handler_file_get
+sl_entity_handler_file_set
+<SUBSECTION Standard>
+SL_ENTITY_HANDLER_FILE
+SL_IS_ENTITY_HANDLER_FILE
+sl_entity_handler_file_get_type
+SL_ENTITY_HANDLER_FILE_CLASS
+SL_IS_ENTITY_HANDLER_FILE_CLASS
+SL_ENTITY_HANDLER_FILE_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>sl-entity-handler-eds</FILE>
+SL_ENTITY_HANDLER_EDS_TYPE
+SlEntityHandlerEDSPriv
+<TITLE>SlEntityHandlerEDS</TITLE>
+SlEntityHandlerEDS
+SlEntityHandlerEDSClass
+sl_entity_handler_eds_new
+sl_entity_handler_eds_get
+sl_entity_handler_eds_set
+sl_entity_handler_eds_get_contact
+<SUBSECTION Standard>
+SL_ENTITY_HANDLER_EDS
+SL_IS_ENTITY_HANDLER_EDS
+sl_entity_handler_eds_get_type
+SL_ENTITY_HANDLER_EDS_CLASS
+SL_IS_ENTITY_HANDLER_EDS_CLASS
+SL_ENTITY_HANDLER_EDS_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>sl-book</FILE>
+<TITLE>SlBook</TITLE>
+SL_BOOK_TYPE
+SL_BOOK_ERROR
+SL_BOOK_DEFAULT
+SlBookPriv
+SlBook
+SlBookClass
+sl_book_error_quark
+sl_book_setup
+sl_book_get_books
+sl_book_exists
+sl_book_create
+sl_book_open
+sl_book_open_default
+sl_book_delete
+sl_book_add_person
+sl_book_remove_person
+sl_book_get_people
+sl_book_get_person
+<SUBSECTION Standard>
+SL_BOOK
+SL_IS_BOOK
+sl_book_get_type
+SL_BOOK_CLASS
+SL_IS_BOOK_CLASS
+SL_BOOK_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>soylent</FILE>
+sl_init
+sl_cleanup
+</SECTION>
Modified: trunk/libsoylent/sl-book.c
==============================================================================
--- trunk/libsoylent/sl-book.c (original)
+++ trunk/libsoylent/sl-book.c Sat Jul 26 12:16:14 2008
@@ -21,6 +21,19 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
+/**
+ * SECTION:sl-book
+ * @short_description: the addressbook
+ * @see_also: #SlEntity
+ * @stability: Unstable
+ * @include: sl-book.h
+ *
+ * SlBook is basically like a real-world addressbook, i.e. it is responsible
+ * for managing people (adding and removing them to / from the addressbook).
+ * Searching for people is also possible. Furthermore SlBook contains utility
+ * functions to create, open and delete addressbooks.
+ */
+
#include "sl-book.h"
#include "sl-priv-util.h"
#include "sl-entity.h"
@@ -91,10 +104,23 @@
GParamSpec *)) sl_book_set_property;
GParamSpec *pspec = NULL;
+
+ /**
+ * SlBook:ebook:
+ *
+ * The underlying #EBook (private).
+ */
pspec = g_param_spec_pointer ("ebook", "ebook", "EBook backend",
G_PARAM_CONSTRUCT_ONLY | G_PARAM_WRITABLE);
-
g_object_class_install_property (obj_class, SL_BOOK_PROPERTY_EBOOK, pspec);
+
+ /**
+ * SlBook::added:
+ * @book: the book that received the signal
+ * @foo: yeah, foo
+ *
+ * Emitted when a person is added to the addressbook.
+ */
}
static void
@@ -194,6 +220,13 @@
return books;
}
+/**
+ * sl_book_exists:
+ *
+ * Deprecated:
+ *
+ * Since: v0.2.0
+ */
gboolean
sl_book_exists (const gchar *name)
{
@@ -210,6 +243,18 @@
return (source != NULL);
}
+/**
+ * sl_book_create:
+ * @name: name of the new addressbook
+ * @error: return location for a GError or NULL
+ *
+ * Creates a new addressbook with the given @name.
+ * There is also a sl_book_open() function. And have you seen our
+ * #SlAttributeHandlerType? Or our %foobar?
+ *
+ * Returns: the created addressbook, or NULL on error. The created addressbook
+ * is immediatly ready for use.
+ */
SlBook *
sl_book_create (const gchar *name, GError **error)
{
Modified: trunk/libsoylent/sl-entity.c
==============================================================================
--- trunk/libsoylent/sl-entity.c (original)
+++ trunk/libsoylent/sl-entity.c Sat Jul 26 12:16:14 2008
@@ -45,6 +45,15 @@
EVCardAttribute *eattr;
};
+/**
+ * SlAttributeHandler:
+ * @type: the type of the handler
+ * @writer: attribute writer function
+ * @reader: attribute reader function
+ *
+ * An attribute-handler is responsible for reading and writing attributes (i.e.
+ * converting them from their runtime-types to a string / binary form and back).
+ */
struct _SlAttributeHandler
{
SlAttributeHandlerType type;
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]