soylent r243 - in trunk: . docs docs/reference docs/reference/libsoylent libsoylent m4



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]