[evolution/express2: 18/51] Document EExtensible and EExtension.

[Michael Meeks <michael src gnome org>]

commit c675132de1981a140cf3341b7b1c3cd08862b54b
Author: Matthew Barnes <mbarnes redhat com>
Date:   Sun Mar 21 14:33:38 2010 -0400

    Document EExtensible and EExtension.
    
    The mechanism here is simple but hard to explain without leaning heavily
    on object-oriented jargon.  Consider this a rough draft.  Illustrations
    would certainly help clarify.

 doc/reference/shell/eshell-docs.sgml       |    2 +
 doc/reference/shell/eshell-sections.txt    |   34 +++++++++++++++++++
 doc/reference/shell/eshell.types           |    2 +
 doc/reference/shell/tmpl/e-extensible.sgml |   33 +++++++++++++++++++
 doc/reference/shell/tmpl/e-extension.sgml  |   39 ++++++++++++++++++++++
 e-util/e-extensible.c                      |   49 ++++++++++++++++++++++++++++
 e-util/e-extension.c                       |   31 +++++++++++++++++
 e-util/e-extension.h                       |    6 +++
 8 files changed, 196 insertions(+), 0 deletions(-)
---
diff --git a/doc/reference/shell/eshell-docs.sgml b/doc/reference/shell/eshell-docs.sgml
index 99948f5..96fae1a 100644
--- a/doc/reference/shell/eshell-docs.sgml
+++ b/doc/reference/shell/eshell-docs.sgml
@@ -34,6 +34,8 @@
     <xi:include href="xml/e-categories-config.xml"/>
     <xi:include href="xml/e-datetime-format.xml"/>
     <xi:include href="xml/e-dialog-utils.xml"/>
+    <xi:include href="xml/e-extensible.xml"/>
+    <xi:include href="xml/e-extension.xml"/>
     <xi:include href="xml/e-html-utils.xml"/>
     <xi:include href="xml/e-icon-factory.xml"/>
     <xi:include href="xml/e-logger.xml"/>
diff --git a/doc/reference/shell/eshell-sections.txt b/doc/reference/shell/eshell-sections.txt
index be5171c..776d08d 100644
--- a/doc/reference/shell/eshell-sections.txt
+++ b/doc/reference/shell/eshell-sections.txt
@@ -441,6 +441,40 @@ e_dialog_combo_box_get
 </SECTION>
 
 <SECTION>
+<FILE>e-extensible</FILE>
+<TITLE>Extensible</TITLE>
+EExtensible
+e_extensible_load_extensions
+<SUBSECTION Standard>
+E_EXTENSIBLE
+E_IS_EXTENSIBLE
+E_TYPE_EXTENSIBLE
+E_EXTENSIBLE_INTERFACE
+E_IS_EXTENSIBLE_INTERFACE
+E_EXTENSIBLE_GET_INTERFACE
+EExtensibleInterface
+e_extensible_get_type
+</SECTION>
+
+<SECTION>
+<FILE>e-extension</FILE>
+<TITLE>Extensions</TITLE>
+EExtension
+e_extension_get_extensible
+<SUBSECTION Standard>
+E_EXTENSION
+E_IS_EXTENSION
+E_TYPE_EXTENSION
+E_EXTENSION_CLASS
+E_IS_EXTENSION_CLASS
+E_EXTENSION_GET_CLASS
+EExtensionClass
+e_extension_get_type
+<SUBSECTION Private>
+EExtensionPrivate
+</SECTION>
+
+<SECTION>
 <FILE>e-html-utils</FILE>
 <TITLE>Text to HTML Conversion</TITLE>
 E_TEXT_TO_HTML_PRE
diff --git a/doc/reference/shell/eshell.types b/doc/reference/shell/eshell.types
index ae84ef0..b5c41ae 100644
--- a/doc/reference/shell/eshell.types
+++ b/doc/reference/shell/eshell.types
@@ -1,4 +1,6 @@
 e_bit_array_get_type
+e_extensible_get_type
+e_extension_get_type
 e_logger_get_type
 e_module_get_type
 e_signature_get_type
diff --git a/doc/reference/shell/tmpl/e-extensible.sgml b/doc/reference/shell/tmpl/e-extensible.sgml
new file mode 100644
index 0000000..de8e8e1
--- /dev/null
+++ b/doc/reference/shell/tmpl/e-extensible.sgml
@@ -0,0 +1,33 @@
+<!-- ##### SECTION Title ##### -->
+Extensible
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT EExtensible ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION e_extensible_load_extensions ##### -->
+<para>
+
+</para>
+
+ extensible: 
+
+
diff --git a/doc/reference/shell/tmpl/e-extension.sgml b/doc/reference/shell/tmpl/e-extension.sgml
new file mode 100644
index 0000000..e1acb9d
--- /dev/null
+++ b/doc/reference/shell/tmpl/e-extension.sgml
@@ -0,0 +1,39 @@
+<!-- ##### SECTION Title ##### -->
+Extensions
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### STRUCT EExtension ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### ARG EExtension:extensible ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION e_extension_get_extensible ##### -->
+<para>
+
+</para>
+
+ extension: 
+ Returns: 
+
+
diff --git a/e-util/e-extensible.c b/e-util/e-extensible.c
index 9960d31..a5e87c4 100644
--- a/e-util/e-extensible.c
+++ b/e-util/e-extensible.c
@@ -16,6 +16,46 @@
  *
  */
 
+/**
+ * SECTION: e-extensible
+ * @short_description: an interface for extending objects
+ * @include: e-util/e-extensible.h
+ *
+ * #EExtension objects can be tacked on to any #GObject instance that
+ * implements the #EExtensible interface.  A #GObject type can be made
+ * extensible in two steps:
+ *
+ * 1. Add the #EExtensible interface when registering the #GType.
+ *    There are no methods to implement.
+ *
+ * <informalexample>
+ * <programlisting>
+ * #include <e-util/e-extensible.h>
+ *
+ * G_DEFINE_TYPE_WITH_CODE (
+ *         ECustomWidget, e_custom_widget, GTK_TYPE_WIDGET,
+ *         G_IMPLEMENT_INTERFACE (E_TYPE_EXTENSIBLE, NULL))
+ * </programlisting>
+ * </informalexample>
+ *
+ * 2. Load extensions for the class at some point during #GObject
+ *    initialization.  Generally this should be done toward the end of
+ *    the initialization code, so extensions get a fully initialized
+ *    object to work with.
+ *
+ * <informalexample>
+ * <programlisting>
+ * static void
+ * e_custom_widget_init (ECustomWidget *widget)
+ * {
+ *         Initialization code goes here...
+ *
+ *         e_extensible_load_extensions (E_EXTENSIBLE (widget));
+ * }
+ * </programlisting>
+ * </informalexample>
+ **/
+
 #include "e-extensible.h"
 
 #include <e-util/e-util.h>
@@ -89,6 +129,15 @@ e_extensible_get_type (void)
 	return type;
 }
 
+/**
+ * e_extensible_load_extensions:
+ * @extensible: an #EExtensible
+ *
+ * Creates an instance of all registered subtypes of #EExtension which
+ * target the class of @extensible.  The lifetimes of these newly created
+ * #EExtension objects are bound to @extensible such that they are finalized
+ * when @extensible is finalized.
+ **/
 void
 e_extensible_load_extensions (EExtensible *extensible)
 {
diff --git a/e-util/e-extension.c b/e-util/e-extension.c
index 05687b6..59eab84 100644
--- a/e-util/e-extension.c
+++ b/e-util/e-extension.c
@@ -16,6 +16,29 @@
  *
  */
 
+/**
+ * SECTION: e-extension
+ * @short_description: abstract base class for extensions
+ * @include: e-util/e-extension.h
+ *
+ * #EExtension provides a way to extend the functionality of objects
+ * that implement the #EExtensible interface.  #EExtension subclasses
+ * can target a particular extensible object type.  New instances of
+ * an extensible object type get paired with a new instance of each
+ * #EExtension subclass that targets the extensible object type.
+ *
+ * The first steps of writing a new extension are as follows:
+ *
+ * 1. Subclass #EExtension.
+ *
+ * 2. In the class initialization function, specify the #GType being
+ *    extended.  The #GType must implement the #EExtensible interface.
+ *
+ * 3. Register the extension's own #GType.  If the extension is to
+ *    be loaded dynamically using #GTypeModule, the type should be
+ *    registered in the library module's e_module_load() function.
+ **/
+
 #include "e-extension.h"
 
 #define E_EXTENSION_GET_PRIVATE(obj) \
@@ -151,6 +174,14 @@ e_extension_init (EExtension *extension)
 	extension->priv = E_EXTENSION_GET_PRIVATE (extension);
 }
 
+/**
+ * e_extension_get_extensible:
+ * @extension: an #EExtension
+ *
+ * Returns the object that @extension extends.
+ *
+ * Returns: the object being extended
+ **/
 EExtensible *
 e_extension_get_extensible (EExtension *extension)
 {
diff --git a/e-util/e-extension.h b/e-util/e-extension.h
index 905ef41..e9eee64 100644
--- a/e-util/e-extension.h
+++ b/e-util/e-extension.h
@@ -47,6 +47,12 @@ typedef struct _EExtension EExtension;
 typedef struct _EExtensionClass EExtensionClass;
 typedef struct _EExtensionPrivate EExtensionPrivate;
 
+/**
+ * EExtension:
+ *
+ * Contains only private data that should be read and manipulated using the
+ * functions below.
+ **/
 struct _EExtension {
 	GObject parent;
 	EExtensionPrivate *priv;