GNOME.org
 

[gnome-panel] doc: Update and complete libpanel-applet API doc

commit 1bccf18e7b4abbf7cac3adebb954e3e122ee6e4e
Author: Vincent Untz <vuntz gnome org>
Date:   Thu Feb 24 23:34:35 2011 +0100

    doc: Update and complete libpanel-applet API doc
    
    Also move the doc inline.

 doc/reference/panel-applet/Makefile.am             |    9 +-
 doc/reference/panel-applet/panel-applet-docs.sgml  |   30 +-
 .../panel-applet/panel-applet-sections.txt         |   40 +--
 .../panel-applet/tmpl/applet-factory.sgml          |   67 ++++
 doc/reference/panel-applet/tmpl/applet.sgml        |  255 +++++++++++++
 doc/reference/panel-applet/tmpl/gconf.sgml         |  166 +++++++++
 .../panel-applet/tmpl/panel-applet-gconf.sgml      |  263 --------------
 .../panel-applet/tmpl/panel-applet-unused.sgml     |  121 -------
 doc/reference/panel-applet/tmpl/panel-applet.sgml  |  380 --------------------
 libpanel-applet/panel-applet-gconf.c               |  150 ++++++++
 libpanel-applet/panel-applet.c                     |  320 ++++++++++++++++-
 libpanel-applet/panel-applet.h                     |   89 +++++
 12 files changed, 1065 insertions(+), 825 deletions(-)
---
diff --git a/doc/reference/panel-applet/Makefile.am b/doc/reference/panel-applet/Makefile.am
index 26eb671..a0e6f5b 100644
--- a/doc/reference/panel-applet/Makefile.am
+++ b/doc/reference/panel-applet/Makefile.am
@@ -18,7 +18,7 @@ DOC_SOURCE_DIR=../../../libpanel-applet
 SCAN_OPTIONS=
 
 # Extra options to supply to gtkdoc-mkdb.
-MKDB_OPTIONS=--output-format=xml
+MKDB_OPTIONS=--xml-mode --output-format=xml
 
 # Extra options to supply to gtkdoc-fixref.
 FIXXREF_OPTIONS=
@@ -29,11 +29,10 @@ CFILE_GLOB=$(top_srcdir)/libpanel-applet/*.c
 
 # Header files to ignore when scanning.
 IGNORE_HFILES =					\
-	GNOME_Panel.h				\
+	panel-applet-bindings.h			\
 	panel-applet-enums.h			\
-	panel-applet-marshal.h			\
-	panel-applet-private.h			\
-	panel-applet-shell.h
+	panel-applet-factory.h			\
+	panel-applet-marshal.h
 
 # Images to copy into HTML directory.
 HTML_IMAGES =
diff --git a/doc/reference/panel-applet/panel-applet-docs.sgml b/doc/reference/panel-applet/panel-applet-docs.sgml
index 20b85a2..4272f26 100644
--- a/doc/reference/panel-applet/panel-applet-docs.sgml
+++ b/doc/reference/panel-applet/panel-applet-docs.sgml
@@ -56,7 +56,7 @@
      <title>Applet Factory</title>
 
      <para>
-      The applet factory is an implementation detail that is mostly hidden by the Panel Applet library, but it still appears in a few places (<link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY"><function>PANEL_APPLET_OUT_PROCESS_FACTORY</function></link>, <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY"><function>PANEL_APPLET_IN_PROCESS_FACTORY</function></link> and <link linkend="getting-started.install.panel-applet"><filename>.panel-applet</filename> files</link>) so it is important to understand what is an applet factory.
+      The applet factory is an implementation detail that is mostly hidden by the Panel Applet library, but it still appears in a few places (<link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link>, <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link> and <link linkend="getting-started.install.panel-applet"><filename>.panel-applet</filename> files</link>) so it is important to understand what is an applet factory.
      </para>
 
      <para>
@@ -68,7 +68,7 @@
      </para>
 
      <para>
-      There is only one applet factory per applet binary, and it is always running before any applet instance is created by the applet binary. The applet factory is created via <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY"><function>PANEL_APPLET_OUT_PROCESS_FACTORY</function></link> or <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY"><function>PANEL_APPLET_IN_PROCESS_FACTORY</function></link>.
+      There is only one applet factory per applet binary, and it is always running before any applet instance is created by the applet binary. The applet factory is created via <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link> or <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link>.
      </para>
 
     </sect2>
@@ -136,7 +136,7 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
     <itemizedlist>
      <listitem>
       <para>
-       <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY"><function>PANEL_APPLET_OUT_PROCESS_FACTORY</function></link>: this creates an <link linkend="getting-started.concepts.applet-factory">applet factory</link> named <constant>HelloWorldFactory</constant>, and each time this applet factory will create an applet instance, it will call <function>hello_world_factory_callback()</function> with a <link linkend="PanelApplet"><type>PanelApplet</type></link> object already created.
+       <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link>: this creates an <link linkend="getting-started.concepts.applet-factory">applet factory</link> named <constant>HelloWorldFactory</constant>, and each time this applet factory will create an applet instance, it will call <function>hello_world_factory_callback()</function> with a <link linkend="PanelApplet"><type>PanelApplet</type></link> object already created.
       </para>
      </listitem>
      <listitem>
@@ -151,13 +151,6 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
      </listitem>
     </itemizedlist>
 
-      <para>libpanel-applet automatically creates a #PanelApplet object
-for you, passing this to your factory method. Here, you should fill
-the applet with your widgets just like a #GtkBin. For example, if you
-were writing a cdplayer applet you would create a #GtkHBox, pack the
-hbox with the cdplayer buttons and in turn add the hbox to the applet.
-      </para>
-
     <para>
      While the previous example is simple, it can be useful to directly subclass the <link linkend="PanelApplet"><type>PanelApplet</type></link> type. This makes it easy to have a per-applet instance private structure, among other benefits.
     </para>
@@ -288,7 +281,7 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
      </para>
 
      <para>
-      To setup the context menu of the applet, the <link linkend="panel-applet-setup-from-file"><function>panel_applet_setup_menu_from_file()</function></link> function should be used, with a path to a <link linkend="getting-started.context-menu.xml-file">menu XML file</link> and a <type>GtkActionGroup</type> object containing all actions that are used in the menu XML file. The example below shows how to achieve this:
+      To setup the context menu of the applet, the <link linkend="panel-applet-setup-menu-from-file"><function>panel_applet_setup_menu_from_file()</function></link> function should be used, with a path to a <link linkend="getting-started.context-menu.xml-file">menu XML file</link> and a <type>GtkActionGroup</type> object containing all actions that are used in the menu XML file. The example below shows how to achieve this:
      </para>
 
      <example>
@@ -408,7 +401,7 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
      </listitem>
      <listitem>
       <para>
-       We also change <function>hello_world_applet_start()</function> to add this <type>GtkActionGroup</type> object to the context menu of the applet, by calling <link linkend="panel-applet-setup-from-file"><function>panel_applet_setup_menu_from_file()</function></link>. This function takes as argument a path to the <link linkend="getting-started.context-menu.xml-file">menu XML file</link> that will define how to display the <type>GtkAction</type> objects in the context menu.
+       We also change <function>hello_world_applet_start()</function> to add this <type>GtkActionGroup</type> object to the context menu of the applet, by calling <link linkend="panel-applet-setup-menu-from-file"><function>panel_applet_setup_menu_from_file()</function></link>. This function takes as argument a path to the <link linkend="getting-started.context-menu.xml-file">menu XML file</link> that will define how to display the <type>GtkAction</type> objects in the context menu.
       </para>
      </listitem>
     </itemizedlist>
@@ -419,7 +412,7 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
      <title>Menu XML File</title>
 
      <para>
-      The file that is used to setup menu with the <link linkend="panel-applet-setup-from-file"><function>panel_applet_setup_menu_from_file()</function></link> function is a <type>GtkUIManager</type> UI definition file, without the top-level <constant>&lt;ui&gt;</constant> tag. It must only contain menuitem entries and separators. For example:
+      The file that is used to setup menu with the <link linkend="panel-applet-setup-menu-from-file"><function>panel_applet_setup_menu_from_file()</function></link> function is a <type>GtkUIManager</type> UI definition file, without the top-level <constant>&lt;ui&gt;</constant> tag. It must only contain menuitem entries and separators. For example:
      </para>
 
      <informalexample>
@@ -431,7 +424,7 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
      </informalexample>
 
     <para>
-     Alternatively, the <link linkend="panel-applet-setup"><function>panel_applet_setup_menu()</function></link> function can be used with a string containing directly the XML.
+     Alternatively, the <link linkend="panel-applet-setup-menu"><function>panel_applet_setup_menu()</function></link> function can be used with a string containing directly the XML.
     </para>
 
     </sect2>
@@ -518,7 +511,7 @@ Icon=hello-world-icon
       <itemizedlist>
        <listitem>
         <para>
-         <constant>Id</constant> (string): the identifier of the applet factory. This must be the same name that will be used as the first parameter to <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY"><function>PANEL_APPLET_OUT_PROCESS_FACTORY</function></link> or <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY"><function>PANEL_APPLET_IN_PROCESS_FACTORY</function></link>.
+         <constant>Id</constant> (string): the identifier of the applet factory. This must be the same name that will be used as the first parameter to <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link> or <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link>.
         </para>
        </listitem>
        <listitem>
@@ -665,7 +658,7 @@ g_object_bind_property (applet, "locked-down",
     <title>Out-of-Process vs In-Process</title>
 
     <para>
-     Applets can either live in their own process ("out-of-process") or in the panel process ("in-process"). The decision to choose one or the other is done at build time, with the macro that you use to define the applet factory: <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY"><function>PANEL_APPLET_OUT_PROCESS_FACTORY</function></link> is used for out-of-process applets while <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY"><function>PANEL_APPLET_IN_PROCESS_FACTORY</function></link> is used for in-process applets. Obviously, only one of those two macros can be used.
+     Applets can either live in their own process ("out-of-process") or in the panel process ("in-process"). The decision to choose one or the other is done at build time, with the macro that you use to define the applet factory: <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link> is used for out-of-process applets while <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link> is used for in-process applets. Obviously, only one of those two macros can be used.
     </para>
 
     <para>
@@ -742,8 +735,9 @@ PanelApplet.Applet.factory_main("HelloWorldFactory",
   <part id="reference">
     <title>API Reference</title>
 
-    <xi:include href="xml/panel-applet.xml"/>
-    <xi:include href="xml/panel-applet-gconf.xml"/>
+    <xi:include href="xml/applet.xml"/>
+    <xi:include href="xml/applet-factory.xml"/>
+    <xi:include href="xml/gconf.xml"/>
   </part>
 
 </book>
diff --git a/doc/reference/panel-applet/panel-applet-sections.txt b/doc/reference/panel-applet/panel-applet-sections.txt
index c674cf0..3f79c11 100644
--- a/doc/reference/panel-applet/panel-applet-sections.txt
+++ b/doc/reference/panel-applet/panel-applet-sections.txt
@@ -1,38 +1,24 @@
 <INCLUDE>panel-applet.h</INCLUDE>
 
 <SECTION>
-<FILE>panel-applet</FILE>
+<FILE>applet</FILE>
+<TITLE>Panel Applet</TITLE>
 PanelApplet
 PanelAppletOrient
-PANEL_APPLET_ORIENT_UP
-PANEL_APPLET_ORIENT_DOWN
-PANEL_APPLET_ORIENT_LEFT
-PANEL_APPLET_ORIENT_RIGHT
-PanelAppletBackgroundType
 PanelAppletFlags
-PanelAppletFactoryCallback
-<TITLE>PanelApplet</TITLE>
-panel_applet_new
 panel_applet_get_orient
 panel_applet_get_size
+panel_applet_set_size_hints
 panel_applet_get_background
-panel_applet_get_preferences_key
-panel_applet_add_preferences
+panel_applet_set_background_widget
 panel_applet_get_flags
 panel_applet_set_flags
-panel_applet_set_size_hints
 panel_applet_get_locked_down
+panel_applet_add_preferences
+panel_applet_get_preferences_key
 panel_applet_request_focus
-panel_applet_get_control
-panel_applet_get_popup_component
 panel_applet_setup_menu
 panel_applet_setup_menu_from_file
-panel_applet_factory_main
-panel_applet_factory_main_closure
-PANEL_APPLET_BONOBO_FACTORY
-panel_applet_shlib_factory
-panel_applet_shlib_factory_closure
-PANEL_APPLET_BONOBO_SHLIB_FACTORY
 <SUBSECTION Standard>
 PANEL_APPLET
 PANEL_IS_APPLET
@@ -44,13 +30,23 @@ PANEL_APPLET_GET_CLASS
 <SUBSECTION Private>
 PanelAppletClass
 PanelAppletPrivate
+panel_applet_factory_setup_in_process
+</SECTION>
+
+<SECTION>
+<FILE>applet-factory</FILE>
+<TITLE>Panel Applet Factory</TITLE>
+PanelAppletFactoryCallback
+PANEL_APPLET_OUT_PROCESS_FACTORY
+PANEL_APPLET_IN_PROCESS_FACTORY
+panel_applet_factory_main
 </SECTION>
 
 <INCLUDE>panel-applet-gconf.h</INCLUDE>
 
 <SECTION>
-<FILE>panel-applet-gconf</FILE>
-<TITLE>Panel Applet GConf Utilities</TITLE>
+<FILE>gconf</FILE>
+<TITLE>GConf Utilities</TITLE>
 panel_applet_gconf_get_full_key
 panel_applet_gconf_get_bool
 panel_applet_gconf_get_int
diff --git a/doc/reference/panel-applet/tmpl/applet-factory.sgml b/doc/reference/panel-applet/tmpl/applet-factory.sgml
new file mode 100644
index 0000000..56fb358
--- /dev/null
+++ b/doc/reference/panel-applet/tmpl/applet-factory.sgml
@@ -0,0 +1,67 @@
+<!-- ##### SECTION Title ##### -->
+Panel Applet Factory
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### USER_FUNCTION PanelAppletFactoryCallback ##### -->
+<para>
+
+</para>
+
+ applet: 
+ iid: 
+ user_data: 
+ Returns: 
+
+
+<!-- ##### MACRO PANEL_APPLET_OUT_PROCESS_FACTORY ##### -->
+<para>
+
+</para>
+
+ id: 
+ type: 
+ callback: 
+ data: 
+
+
+<!-- ##### MACRO PANEL_APPLET_IN_PROCESS_FACTORY ##### -->
+<para>
+
+</para>
+
+ id: 
+ type: 
+ callback: 
+ data: 
+
+
+<!-- ##### FUNCTION panel_applet_factory_main ##### -->
+<para>
+
+</para>
+
+ factory_id: 
+ applet_type: 
+ callback: 
+ data: 
+ Returns: 
+
+
diff --git a/doc/reference/panel-applet/tmpl/applet.sgml b/doc/reference/panel-applet/tmpl/applet.sgml
new file mode 100644
index 0000000..eddf72b
--- /dev/null
+++ b/doc/reference/panel-applet/tmpl/applet.sgml
@@ -0,0 +1,255 @@
+<!-- ##### SECTION Title ##### -->
+Panel Applet
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### STRUCT PanelApplet ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SIGNAL PanelApplet::change-background ##### -->
+<para>
+
+</para>
+
+ panelapplet: the object which received the signal.
+ arg1: 
+
+<!-- ##### SIGNAL PanelApplet::change-orient ##### -->
+<para>
+
+</para>
+
+ panelapplet: the object which received the signal.
+ arg1: 
+
+<!-- ##### SIGNAL PanelApplet::change-size ##### -->
+<para>
+
+</para>
+
+ panelapplet: the object which received the signal.
+ arg1: 
+
+<!-- ##### SIGNAL PanelApplet::move-focus-out-of-applet ##### -->
+<para>
+
+</para>
+
+ panelapplet: the object which received the signal.
+ arg1: 
+
+<!-- ##### ARG PanelApplet:background ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:closure ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:connection ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:flags ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:id ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:locked ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:locked-down ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:orient ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:prefs-key ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:size ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG PanelApplet:size-hints ##### -->
+<para>
+
+</para>
+
+<!-- ##### ENUM PanelAppletOrient ##### -->
+<para>
+
+</para>
+
+ PANEL_APPLET_ORIENT_UP: 
+ PANEL_APPLET_ORIENT_DOWN: 
+ PANEL_APPLET_ORIENT_LEFT: 
+
+<!-- ##### ENUM PanelAppletFlags ##### -->
+<para>
+
+</para>
+
+ PANEL_APPLET_FLAGS_NONE: 
+ PANEL_APPLET_EXPAND_MAJOR: 
+ PANEL_APPLET_EXPAND_MINOR: 
+
+<!-- ##### FUNCTION panel_applet_get_orient ##### -->
+<para>
+
+</para>
+
+ applet: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_get_size ##### -->
+<para>
+
+</para>
+
+ applet: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_set_size_hints ##### -->
+<para>
+
+</para>
+
+ applet: 
+ size_hints: 
+ n_elements: 
+ base_size: 
+
+
+<!-- ##### FUNCTION panel_applet_get_background ##### -->
+<para>
+
+</para>
+
+ applet: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_set_background_widget ##### -->
+<para>
+
+</para>
+
+ applet: 
+ widget: 
+
+
+<!-- ##### FUNCTION panel_applet_get_flags ##### -->
+<para>
+
+</para>
+
+ applet: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_set_flags ##### -->
+<para>
+
+</para>
+
+ applet: 
+ flags: 
+
+
+<!-- ##### FUNCTION panel_applet_get_locked_down ##### -->
+<para>
+
+</para>
+
+ applet: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_add_preferences ##### -->
+<para>
+
+</para>
+
+ applet: 
+ schema_dir: 
+ error: 
+
+
+<!-- ##### FUNCTION panel_applet_get_preferences_key ##### -->
+<para>
+
+</para>
+
+ applet: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_request_focus ##### -->
+<para>
+
+</para>
+
+ applet: 
+ timestamp: 
+
+
+<!-- ##### FUNCTION panel_applet_setup_menu ##### -->
+<para>
+
+</para>
+
+ applet: 
+ xml: 
+ action_group: 
+
+
+<!-- ##### FUNCTION panel_applet_setup_menu_from_file ##### -->
+<para>
+
+</para>
+
+ applet: 
+ filename: 
+ action_group: 
+
+
diff --git a/doc/reference/panel-applet/tmpl/gconf.sgml b/doc/reference/panel-applet/tmpl/gconf.sgml
new file mode 100644
index 0000000..0c1e822
--- /dev/null
+++ b/doc/reference/panel-applet/tmpl/gconf.sgml
@@ -0,0 +1,166 @@
+<!-- ##### SECTION Title ##### -->
+GConf Utilities
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
+<!-- ##### FUNCTION panel_applet_gconf_get_full_key ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_get_bool ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ error: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_get_int ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ error: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_get_string ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ error: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_get_float ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ error: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_get_list ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ list_type: 
+ error: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_get_value ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ error: 
+ Returns: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_set_bool ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ the_bool: 
+ error: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_set_int ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ the_int: 
+ error: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_set_string ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ the_string: 
+ error: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_set_float ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ the_float: 
+ error: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_set_list ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ list_type: 
+ list: 
+ error: 
+
+
+<!-- ##### FUNCTION panel_applet_gconf_set_value ##### -->
+<para>
+
+</para>
+
+ applet: 
+ key: 
+ value: 
+ error: 
+
+
diff --git a/doc/reference/panel-applet/tmpl/panel-applet-unused.sgml b/doc/reference/panel-applet/tmpl/panel-applet-unused.sgml
index 5d08c73..e69de29 100644
--- a/doc/reference/panel-applet/tmpl/panel-applet-unused.sgml
+++ b/doc/reference/panel-applet/tmpl/panel-applet-unused.sgml
@@ -1,121 +0,0 @@
-<!-- ##### MACRO PANEL_APPLET_BONOBO_FACTORY ##### -->
-<para>
-Defines a 'main' routine for the applet factory.
-</para>
-
- iid: The bonobo-activation iid of the factory.
- type: The #GType to instantiate.
- name: The applet ID string.
- version: The applet version string.
- callback: The factory callback.
- data: The factory user data pointer.
-
-<!-- ##### MACRO PANEL_APPLET_BONOBO_SHLIB_FACTORY ##### -->
-<para>
-Defines a Bonobo Activation shared library plugin and associated
-factory callback.
-</para>
-
- iid: The bonobo-activation iid of the factory.
- type: The #GType to instantiate.
- descr: A description of the applet.
- callback: The factory callback.
- data: The factory user data pointer.
-
-<!-- ##### MACRO PANEL_APPLET_ORIENT_DOWN ##### -->
-<para>
-The applet is orientated down (i.e. the panel is at the top of the screen).
-</para>
-
-
-<!-- ##### MACRO PANEL_APPLET_ORIENT_LEFT ##### -->
-<para>
-The applet is orientated left (i.e. the panel is at the right hand side of the screen).
-</para>
-
-
-<!-- ##### MACRO PANEL_APPLET_ORIENT_RIGHT ##### -->
-<para>
-The applet is orientated right (i.e. the panel is at the left hand side of the screen).
-</para>
-
-
-<!-- ##### MACRO PANEL_APPLET_ORIENT_UP ##### -->
-<para>
-The applet is orientated up (i.e. the panel is at the bottom of the screen).
-</para>
-
-
-<!-- ##### ENUM PanelAppletBackgroundType ##### -->
-<para>
-The #PanelAppletBackgroundType enumerated type specifies the type of
-background of a panel.
-</para>
-
- PANEL_NO_BACKGROUND: The panel has no background, the default is used.
- PANEL_COLOR_BACKGROUND: The panel has a color, i.e rgb value,
-background.
- PANEL_PIXMAP_BACKGROUND:  The panel has either an image background
-or is translucent.
-
-<!-- ##### FUNCTION panel_applet_factory_main_closure ##### -->
-<para>
-A generic 'main' routine for applets. This should not normally be
-used directly because it is invoked by #PANEL_APPLET_BONOBO_FACTORY.
-</para>
-
- iid: The bonobo-activation iid of the factory.
- applet_type: The #GType to instantiate.
- closure: The factory callback closure.
- Returns: 0 on success, 1 on failure.
-
-<!-- ##### FUNCTION panel_applet_get_control ##### -->
-<para>
-Retrieves the #BonoboControl associated with @applet.
-</para>
-
- applet: The #PanelApplet.
- Returns: A #BonoboControl.
-
-<!-- ##### FUNCTION panel_applet_get_popup_component ##### -->
-<para>
-Retrieves the #BonoboUIComponent used for popup menus associated
-with @applet.
-</para>
-
- applet: The #PanelApplet.
- Returns: A #BonoboUIComponent.
-
-<!-- ##### FUNCTION panel_applet_shlib_factory ##### -->
-<para>
-A generic shared library factory routine for applets. This should not
-normally be used directly as it is invoked by #PANEL_APPLET_BONOBO_SHLIB_FACTORY.
-</para>
-
- iid: The bonobo-activation iid of the factory.
- applet_type: The #GType to instantiate.
- poa: The #PortableServer_POA passed to the shlib factory
-callback.
- impl_ptr: The #gpointer passed to the shlib factory callback.
- callback: The applet factory callback.
- user_data: The factory user data pointer.
- ev: The $CORBA_Environment passed to the shlib factory callback.
- Returns: A #Bonobo_Unknown to return from the shlib factory
-callback.
-
-<!-- ##### FUNCTION panel_applet_shlib_factory_closure ##### -->
-<para>
-A generic shared library factory routine for applets. This should not
-normally be used directly as it is invoked by #PANEL_APPLET_BONOBO_SHLIB_FACTORY.
-</para>
-
- iid: The bonobo-activation iid of the factory.
- applet_type: The #GType to instantiate.
- poa: The #PortableServer_POA passed to the shlib factory
-callback.
- impl_ptr: The #gpointer passed to the shlib factory callback.
- closure: The applet factory closure.
- ev: The $CORBA_Environment passed to the shlib factory callback.
- Returns: A #Bonobo_Unknown to return from the shlib factory
-callback.
-
diff --git a/libpanel-applet/panel-applet-gconf.c b/libpanel-applet/panel-applet-gconf.c
index 2e569f5..f7b4575 100644
--- a/libpanel-applet/panel-applet-gconf.c
+++ b/libpanel-applet/panel-applet-gconf.c
@@ -26,6 +26,20 @@
 
 #include "panel-applet-gconf.h"
 
+/**
+ * SECTION:gconf
+ * @short_description: utility API to use GConf with applets.
+ * @stability: Unstable
+ *
+ * The <function>panel_applet_gconf_*()</function> set of API provides
+ * convenience functions to access GConf keys that are specific to an
+ * applet instance.
+ *
+ * Keep in mind that it might be worth considering using <link
+ * linkend="getting-started.settings">global settings</link> for your applet,
+ * instead of settings specific to an instance.
+ */
+
 static GConfClient *
 panel_applet_gconf_get_client (void)
 {
@@ -37,6 +51,14 @@ panel_applet_gconf_get_client (void)
 	return client;
 }
 
+/**
+ * panel_applet_gconf_get_full_key:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ *
+ * Returns the full GConf path of @key, in the per-instance GConf directory of
+ * @applet. The string should be freed by the caller.
+ **/
 gchar *
 panel_applet_gconf_get_full_key (PanelApplet *applet,
 				 const gchar *key)
@@ -58,6 +80,16 @@ panel_applet_gconf_get_full_key (PanelApplet *applet,
 	return full_key;
 }
 
+/**
+ * panel_applet_gconf_set_bool:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @the_bool: new value for @key.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_set_bool() to update @key in the
+ * per-instance GConf directory of @applet.
+ **/
 void
 panel_applet_gconf_set_bool (PanelApplet  *applet,
 			     const gchar  *key,
@@ -90,6 +122,16 @@ panel_applet_gconf_set_bool (PanelApplet  *applet,
 	}
 }
 
+/**
+ * panel_applet_gconf_set_int:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @the_int: new value for @key.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_set_int() to update @key in the
+ * per-instance GConf directory of @applet.
+ **/
 void
 panel_applet_gconf_set_int (PanelApplet  *applet,
 			    const gchar  *key,
@@ -122,6 +164,16 @@ panel_applet_gconf_set_int (PanelApplet  *applet,
 	}
 }
 
+/**
+ * panel_applet_gconf_set_string:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @the_string: new value for @key.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_set_string() to update @key in the
+ * per-instance GConf directory of @applet.
+ **/
 void
 panel_applet_gconf_set_string (PanelApplet  *applet,
 			       const gchar  *key,
@@ -154,6 +206,16 @@ panel_applet_gconf_set_string (PanelApplet  *applet,
 	}
 }
 
+/**
+ * panel_applet_gconf_set_float:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @the_float: new value for @key.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_set_float() to update @key in the
+ * per-instance GConf directory of @applet.
+ **/
 void
 panel_applet_gconf_set_float (PanelApplet  *applet,
 			      const gchar  *key,
@@ -186,6 +248,17 @@ panel_applet_gconf_set_float (PanelApplet  *applet,
 	}
 }
 
+/**
+ * panel_applet_gconf_set_list:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @list_type: type of items in @list.
+ * @list: new value for @key.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_set_list() to update @key in the
+ * per-instance GConf directory of @applet.
+ **/
 void
 panel_applet_gconf_set_list (PanelApplet     *applet,
 			     const gchar     *key,
@@ -219,6 +292,16 @@ panel_applet_gconf_set_list (PanelApplet     *applet,
 	}
 }
 
+/**
+ * panel_applet_gconf_set_value:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @value: new value for @key.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_set_value() to update @key in the
+ * per-instance GConf directory of @applet.
+ **/
 void
 panel_applet_gconf_set_value (PanelApplet  *applet,
 			      const gchar  *key,
@@ -251,6 +334,17 @@ panel_applet_gconf_set_value (PanelApplet  *applet,
 	}
 }
 
+/**
+ * panel_applet_gconf_get_bool:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_get_bool() to get the value of @key
+ * in the per-instance GConf directory of @applet.
+ *
+ * Returns: the value of @key.
+ **/
 gboolean
 panel_applet_gconf_get_bool (PanelApplet  *applet,
 			     const gchar  *key,
@@ -285,6 +379,17 @@ panel_applet_gconf_get_bool (PanelApplet  *applet,
 	return retval;
 }
 
+/**
+ * panel_applet_gconf_get_int:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_get_int() to get the value of @key
+ * in the per-instance GConf directory of @applet.
+ *
+ * Returns: the value of @key.
+ **/
 gint
 panel_applet_gconf_get_int (PanelApplet  *applet,
 			    const gchar  *key,
@@ -319,6 +424,17 @@ panel_applet_gconf_get_int (PanelApplet  *applet,
 	return retval;
 }
 
+/**
+ * panel_applet_gconf_get_string:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_get_string() to get the value of @key
+ * in the per-instance GConf directory of @applet.
+ *
+ * Returns: the value of @key. The string should be freed by the caller.
+ **/
 gchar *
 panel_applet_gconf_get_string (PanelApplet  *applet,
 			       const gchar  *key,
@@ -353,6 +469,17 @@ panel_applet_gconf_get_string (PanelApplet  *applet,
 	return retval;
 }
 
+/**
+ * panel_applet_gconf_get_float:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_get_float() to get the value of @key
+ * in the per-instance GConf directory of @applet.
+ *
+ * Returns: the value of @key.
+ **/
 gdouble
 panel_applet_gconf_get_float (PanelApplet  *applet,
 			      const gchar  *key,
@@ -387,6 +514,17 @@ panel_applet_gconf_get_float (PanelApplet  *applet,
 	return retval;
 }
 
+/**
+ * panel_applet_gconf_get_value:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_get_value() to get the value of @key
+ * in the per-instance GConf directory of @applet.
+ *
+ * Returns: the value of @key.
+ **/
 GConfValue *
 panel_applet_gconf_get_value (PanelApplet  *applet,
 			      const gchar  *key,
@@ -421,6 +559,18 @@ panel_applet_gconf_get_value (PanelApplet  *applet,
 	return retval;
 }
 
+/**
+ * panel_applet_gconf_get_list:
+ * @applet: a #PanelApplet.
+ * @key: a GConf key name.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Convenience wrapper around gconf_client_get_list() to get the value of @key
+ * in the per-instance GConf directory of @applet.
+ *
+ * Returns: the value of @key. The list and its content should be freed by the
+ * caller.
+ **/
 GSList *
 panel_applet_gconf_get_list (PanelApplet     *applet,
 			     const gchar     *key,
diff --git a/libpanel-applet/panel-applet.c b/libpanel-applet/panel-applet.c
index d06bd6c..a5c667b 100644
--- a/libpanel-applet/panel-applet.c
+++ b/libpanel-applet/panel-applet.c
@@ -49,6 +49,34 @@
 #include "panel-applet-marshal.h"
 #include "panel-applet-enums.h"
 
+/**
+ * SECTION:applet
+ * @short_description: a widget embedded in a panel.
+ * @stability: Unstable
+ *
+ * Applets are small applications that are embedded in the GNOME panel. They
+ * can be used to give quick access to some features, or to display the state
+ * of something specific.
+ *
+ * The #PanelApplet API hides all of the embedding process as it handles all
+ * the communication with the GNOME panel. It is a subclass of #GtkBin, so you
+ * can add any kind of widgets to it.
+ *
+ * See the <link linkend="getting-started">Getting Started</link> section to
+ * learn how to properly use #PanelApplet.
+ */
+
+/**
+ * SECTION:applet-factory
+ * @short_description: the factory that will create applets.
+ * @stability: Unstable
+ *
+ * This API is used to create an <link
+ * linkend="getting-started.concepts.applet-factory">applet factory</link>. You
+ * need to call one and only one of these functions to get applets working in
+ * your binary.
+ */
+
 #define PANEL_APPLET_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), PANEL_TYPE_APPLET, PanelAppletPrivate))
 
 struct _PanelAppletPrivate {
@@ -260,6 +288,17 @@ panel_applet_associate_schemas_in_dir (GConfClient  *client,
 	g_slist_free (list);
 }
 
+/**
+ * panel_applet_add_preferences:
+ * @applet: a #PanelApplet.
+ * @schema_dir: a GConf path of a schema directory.
+ * @opt_error: a #GError, or %NULL.
+ *
+ * Associates the per-instance GConf directory of @applet to the schemas
+ * defined in @schema_dir. This must be called if the applet will save
+ * per-instance settings, to ensure that each key in the per-instance GConf
+ * directory has a defined type, sane default and documentation.
+ **/
 void
 panel_applet_add_preferences (PanelApplet  *applet,
 			      const gchar  *schema_dir,
@@ -291,6 +330,14 @@ panel_applet_add_preferences (PanelApplet  *applet,
 	}
 }
 
+/**
+ * panel_applet_get_preferences_key:
+ * @applet: a #PanelApplet.
+ *
+ * Gets the GConf path to the per-instance settings of @applet.
+ *
+ * Returns: a copy of the GConf path to the per-instance settings of @applet.
+ **/
 char *
 panel_applet_get_preferences_key (PanelApplet *applet)
 {
@@ -333,6 +380,14 @@ panel_applet_set_preferences_key (PanelApplet *applet,
 	g_object_notify (G_OBJECT (applet), "prefs-key");
 }
 
+/**
+ * panel_applet_get_flags:
+ * @applet: a #PanelApplet.
+ *
+ * Gets the #PanelAppletFlags of @applet.
+ *
+ * Returns: the #PanelAppletFlags of @applet.
+ **/
 PanelAppletFlags
 panel_applet_get_flags (PanelApplet *applet)
 {
@@ -341,6 +396,14 @@ panel_applet_get_flags (PanelApplet *applet)
 	return applet->priv->flags;
 }
 
+/**
+ * panel_applet_set_flags:
+ * @applet: a #PanelApplet.
+ * @flags: #PanelAppletFlags to use for @applet.
+ *
+ * Sets the #PanelAppletFlags of @applet. Most of the time, at least
+ * %PANEL_APPLET_EXPAND_MINOR should be used.
+ **/
 void
 panel_applet_set_flags (PanelApplet      *applet,
 			PanelAppletFlags  flags)
@@ -418,6 +481,28 @@ panel_applet_size_hints_changed (PanelApplet *applet,
 	return FALSE;
 }
 
+/**
+ * panel_applet_set_size_hints:
+ * @applet: a #PanelApplet.
+ * @size_hints: array of sizes.
+ * @n_elements: length of @size_hints.
+ * @base_size: base size of the applet.
+ *
+ * Give hints to the panel about sizes @applet is comfortable with. This is
+ * generally useful for applets that can take a lot of space, in case the panel
+ * gets full and needs to restrict the size of some applets.
+ *
+ * @size_hints should have an even number of sizes. It is an array of (max,
+ * min) pairs where min(i) > max(i + 1).
+ *
+ * @base_size will be added to all sizes in @size_hints, and is therefore a way
+ * to guarantee a minimum size to @applet.
+ *
+ * The panel will try to allocate a size that is acceptable to @applet, i.e. in
+ * one of the (@base_size + max, @base_size + min) ranges.
+ *
+ * %PANEL_APPLET_EXPAND_MAJOR must be set for @applet to use size hints.
+ **/
 void
 panel_applet_set_size_hints (PanelApplet *applet,
 			     const int   *size_hints,
@@ -471,6 +556,18 @@ panel_applet_set_size_hints (PanelApplet *applet,
 	}
 }
 
+/**
+ * panel_applet_get_size:
+ * @applet: a #PanelApplet.
+ *
+ * Gets the size of the panel @applet is on. For a horizontal panel, the
+ * size if the height of the panel; for a vertical panel, the size is the width
+ * of the panel.
+ *
+ * Returns: the size of the panel @applet is on.
+ *
+ * Deprecated: 3.0: Use the allocation of @applet instead.
+ **/
 guint
 panel_applet_get_size (PanelApplet *applet)
 {
@@ -497,6 +594,14 @@ panel_applet_set_size (PanelApplet *applet,
 	g_object_notify (G_OBJECT (applet), "size");
 }
 
+/**
+ * panel_applet_get_orient:
+ * @applet: a #PanelApplet.
+ *
+ * Gets the #PanelAppletOrient of @applet.
+ *
+ * Returns: the #PanelAppletOrient of @applet.
+ **/
 PanelAppletOrient
 panel_applet_get_orient (PanelApplet *applet)
 {
@@ -579,6 +684,15 @@ panel_applet_set_locked (PanelApplet *applet,
 	}
 }
 
+/**
+ * panel_applet_get_locked_down:
+ * @applet: a #PanelApplet.
+ *
+ * Gets whether the panel @applet is on is locked down or not. A locked down
+ * applet should not allow any change to its configuration.
+ *
+ * Returns: %TRUE if the panel @applet is on is locked down, %FALSE otherwise.
+ **/
 gboolean
 panel_applet_get_locked_down (PanelApplet *applet)
 {
@@ -687,6 +801,15 @@ panel_applet_find_toplevel_dock_window (PanelApplet *applet,
 	return None;
 }
 
+/**
+ * panel_applet_request_focus:
+ * @applet: a #PanelApplet.
+ * @timestamp: the timestamp of the user interaction (typically a button or key
+ * press event) which triggered this call.
+ *
+ * Requests focus for @applet. There is no guarantee that @applet will
+ * successfully get focus after that call.
+ **/
 /* This function
  *   1) Gets the window id of the panel that contains the applet
  *	using XQueryTree and XGetWindowProperty to find an ancestor
@@ -817,6 +940,19 @@ panel_applet_menu_cmd_lock (GtkAction   *action,
 	panel_applet_set_locked (applet, locked);
 }
 
+/**
+ * panel_applet_setup_menu:
+ * @applet: a #PanelApplet.
+ * @xml: a menu XML string.
+ * @applet_action_group: a #GtkActionGroup.
+ *
+ * Sets up the context menu of @applet. @xml is a #GtkUIManager UI definition,
+ * describing how to display the menu items. @applet_action_group contains the
+ * various #GtkAction that are referenced in @xml.
+ *
+ * See also the <link linkend="getting-started.context-menu">Context
+ * Menu</link> section.
+ **/
 void
 panel_applet_setup_menu (PanelApplet    *applet,
 			 const gchar    *xml,
@@ -847,6 +983,20 @@ panel_applet_setup_menu (PanelApplet    *applet,
 	}
 }
 
+/**
+ * panel_applet_setup_menu_from_file:
+ * @applet: a #PanelApplet.
+ * @filename: path to a menu XML file.
+ * @applet_action_group: a #GtkActionGroup.
+ *
+ * Sets up the context menu of @applet. @filename is the path to a menu XML
+ * file, containing a #GtkUIManager UI definition that describes how to display
+ * the menu items. @applet_action_group contains the various #GtkAction that
+ * are referenced in @xml.
+ *
+ * See also the <link linkend="getting-started.context-menu">Context
+ * Menu</link> section.
+ **/
 void
 panel_applet_setup_menu_from_file (PanelApplet    *applet,
 				   const gchar    *filename,
@@ -1488,12 +1638,13 @@ panel_applet_get_pattern_from_pixmap (PanelApplet *applet,
 
 /**
  * panel_applet_get_background:
- * @applet: a #PanelApplet
+ * @applet: a #PanelApplet.
  *
- * Returns the background pattern for @applet, or %NULL if there is none.
+ * Gets the background pattern for @applet, or %NULL if there is none.
  *
- * Returns: (transfer full): a new #cairo_pattern_t
- */
+ * Returns: (transfer full): a new #cairo_pattern_t to use as background for
+ * @applet.
+ **/
 cairo_pattern_t *
 panel_applet_get_background (PanelApplet *applet)
 {
@@ -1938,6 +2089,11 @@ panel_applet_class_init (PanelAppletClass *klass)
 
 	g_type_class_add_private (klass, sizeof (PanelAppletPrivate));
 
+	/**
+	 * PanelApplet:id: (skip)
+	 *
+	 * Implementation detail.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_ID,
 					 g_param_spec_string ("id",
@@ -1946,6 +2102,11 @@ panel_applet_class_init (PanelAppletClass *klass)
 							      NULL,
 							      G_PARAM_CONSTRUCT_ONLY |
 							      G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:closure: (skip)
+	 *
+	 * Implementation detail.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_CLOSURE,
 					 g_param_spec_pointer ("closure",
@@ -1953,6 +2114,11 @@ panel_applet_class_init (PanelAppletClass *klass)
 							       "The Applet closure",
 							       G_PARAM_CONSTRUCT_ONLY |
 							       G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:connection: (skip)
+	 *
+	 * Implementation detail.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_CONNECTION,
 					 g_param_spec_object ("connection",
@@ -1961,6 +2127,13 @@ panel_applet_class_init (PanelAppletClass *klass)
 							      G_TYPE_DBUS_CONNECTION,
 							      G_PARAM_CONSTRUCT_ONLY |
 							      G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:prefs-key:
+	 *
+	 * The GConf path to the per-instance settings of the applet.
+	 *
+	 * This property gets set when the applet gets embedded.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_PREFS_KEY,
 					 g_param_spec_string ("prefs-key",
@@ -1968,7 +2141,14 @@ panel_applet_class_init (PanelAppletClass *klass)
 							      "GConf Preferences Key",
 							      NULL,
 							      G_PARAM_READWRITE));
-        // FIXMEchpe GtkOrientation?
+	/**
+	 * PanelApplet:orient:
+	 *
+	 * The #PanelAppletOrient of the applet.
+	 *
+	 * This property gets set when the applet gets embedded, and can change
+	 * when the panel position changes.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_ORIENT,
 					 g_param_spec_uint ("orient",
@@ -1976,6 +2156,18 @@ panel_applet_class_init (PanelAppletClass *klass)
 							    "Panel Applet Orientation",
 							    0, G_MAXUINT, 0, /* FIXME */
 							    G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:size:
+	 *
+	 * The size of the panel the applet is on. For a horizontal panel, the
+	 * size if the height of the panel; for a vertical panel, the size is
+	 * the width of the panel.
+	 *
+	 * This property gets set when the applet gets embedded, and can change
+	 * when the panel size changes.
+         *
+	 * Deprecated: 3.0: Use the allocation of @applet instead.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_SIZE,
 					 g_param_spec_uint ("size",
@@ -1983,6 +2175,11 @@ panel_applet_class_init (PanelAppletClass *klass)
 							    "Panel Applet Size",
 							    0, G_MAXUINT, 0,
 							    G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:background: (skip)
+	 *
+	 * Implementation detail.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_BACKGROUND,
 					 g_param_spec_string ("background",
@@ -1990,6 +2187,11 @@ panel_applet_class_init (PanelAppletClass *klass)
 							      "Panel Applet Background",
 							      NULL,
 							      G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:flags:
+	 *
+	 * The #PanelAppletFlags of the applet.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_FLAGS,
 					 g_param_spec_uint ("flags",
@@ -1997,28 +2199,50 @@ panel_applet_class_init (PanelAppletClass *klass)
 							    "Panel Applet flags",
 							    0, G_MAXUINT, 0, /* FIXME */
 							    G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:size-hints:
+	 *
+	 * The size hints set for the applet. See panel_applet_set_size_hints().
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_SIZE_HINTS,
 					 /* FIXME: value_array? */
 					 g_param_spec_pointer ("size-hints",
 							       "SizeHints",
-							       "Panel Applet Size Hints",
+							       "Size hints of the applet",
 							       G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:locked:
+	 *
+	 * Whether the position of the applet is locked.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_LOCKED,
 					 g_param_spec_boolean ("locked",
 							       "Locked",
-							       "Whether Panel Applet is locked",
+							       "Whether the position of the applet is locked",
 							       FALSE,
 							       G_PARAM_READWRITE));
+	/**
+	 * PanelApplet:locked-down:
+	 *
+	 * Whether the panel the applet is on is locked down.
+	 **/
 	g_object_class_install_property (gobject_class,
 					 PROP_LOCKED_DOWN,
 					 g_param_spec_boolean ("locked-down",
 							       "LockedDown",
-							       "Whether Panel Applet is locked down",
+							       "Whether the panel the applet is on is locked down",
 							       FALSE,
 							       G_PARAM_READWRITE));
 
+        /**
+         * PanelApplet::change-orient:
+         * @applet: the #PanelApplet which emitted the signal.
+         * @orient: the new #PanelAppletOrient of @applet.
+         *
+         * Emitted when the #PanelAppletOrient of @applet has changed.
+         **/
 	panel_applet_signals [CHANGE_ORIENT] =
                 g_signal_new ("change_orient",
                               G_TYPE_FROM_CLASS (klass),
@@ -2031,6 +2255,15 @@ panel_applet_class_init (PanelAppletClass *klass)
 			      1,
 			      G_TYPE_UINT);
 
+        /**
+         * PanelApplet::change-size:
+         * @applet: the #PanelApplet which emitted the signal.
+         * @size: the new size of the panel @applet is on.
+         *
+         * Emitted when the size of the panel @applet is on has changed.
+	 *
+	 * Deprecated: 3.0: Use the #GtkWidget::size-allocate signal instead.
+         **/
 	panel_applet_signals [CHANGE_SIZE] =
                 g_signal_new ("change_size",
                               G_TYPE_FROM_CLASS (klass),
@@ -2043,6 +2276,13 @@ panel_applet_class_init (PanelAppletClass *klass)
 			      1,
 			      G_TYPE_INT);
 
+        /**
+         * PanelApplet::change-background:
+         * @applet: the #PanelApplet which emitted the signal.
+         * @pattern: the new background pattern for @applet, or %NULL if there is none.
+         *
+         * Emitted when the background of @applet has changed.
+         **/
 	panel_applet_signals [CHANGE_BACKGROUND] =
                 g_signal_new ("change_background",
                               G_TYPE_FROM_CLASS (klass),
@@ -2055,6 +2295,14 @@ panel_applet_class_init (PanelAppletClass *klass)
 			      1,
 			      CAIRO_GOBJECT_TYPE_PATTERN);
 
+        /**
+         * PanelApplet::move-focus-out-of-applet: (skip)
+         * @applet: the #PanelApplet which emitted the signal.
+         * @direction: the move direction.
+         *
+	 * Emitted when the focus is moved out of @applet. This is an
+	 * implementation detail.
+         **/
 	panel_applet_signals [MOVE_FOCUS_OUT_OF_APPLET] =
                 g_signal_new ("move_focus_out_of_applet",
                               G_TYPE_FROM_CLASS (klass),
@@ -2342,13 +2590,30 @@ _panel_applet_factory_main_internal (const gchar               *factory_id,
 
 /**
  * panel_applet_factory_main:
- * @factory_id: Factory ID.
+ * @factory_id: identifier of an applet factory.
  * @applet_type: GType of the applet this factory creates.
- * @callback: (scope call): Callback to be called when a new applet is to be created.
- * @data: (closure): Callback data.
+ * @callback: (scope call): callback to be called when a new applet is created.
+ * @user_data: (closure): callback data.
+ *
+ * Creates the applet factory for @factory_id, so that the factory can create
+ * instances of the applet types it is associated with.
+ *
+ * Applet instances created by the applet factory will use @applet_type as
+ * GType. Unless you subclass #PanelApplet, you should use %PANEL_TYPE_APPLET
+ * as @applet_type.
+ *
+ * On creation of the applet instances, @callback is called to setup the
+ * applet. If @callback returns %FALSE, the creation of the applet instance is
+ * cancelled.
+ *
+ * If using C, it is recommended to use #PANEL_APPLET_OUT_PROCESS_FACTORY
+ * instead as it will create a main() function for you.
+ *
+ * It can only be used once, and is incompatible with the use of
+ * %PANEL_APPLET_IN_PROCESS_FACTORY and %PANEL_APPLET_OUT_PROCESS_FACTORY.
  *
  * Returns: 0 on success, 1 if there is an error.
- */
+ **/
 int
 panel_applet_factory_main (const gchar               *factory_id,
 			   GType                      applet_type,
@@ -2361,13 +2626,27 @@ panel_applet_factory_main (const gchar               *factory_id,
 
 /**
  * panel_applet_factory_setup_in_process: (skip)
- * @factory_id: Factory ID.
+ * @factory_id: identifier of an applet factory.
  * @applet_type: GType of the applet this factory creates.
- * @callback: (scope call): Callback to be called when a new applet is to be created.
- * @data: (closure): Callback data.
+ * @callback: (scope call): callback to be called when a new applet is created.
+ * @user_data: (closure): callback data.
+ *
+ * Creates the applet factory for @factory_id, so that the factory can create
+ * instances of the applet types it is associated with.
+ *
+ * Applet instances created by the applet factory will use @applet_type as
+ * GType. Unless you subclass #PanelApplet, you should use %PANEL_TYPE_APPLET
+ * as @applet_type.
+ *
+ * On creation of the applet instances, @callback is called to setup the
+ * applet. If @callback returns %FALSE, the creation of the applet instance is
+ * cancelled.
+ *
+ * It can only be used once, and is incompatible with the use of
+ * %PANEL_APPLET_IN_PROCESS_FACTORY and %PANEL_APPLET_OUT_PROCESS_FACTORY.
  *
  * Returns: 0 on success, 1 if there is an error.
- */
+ **/
 int
 panel_applet_factory_setup_in_process (const gchar               *factory_id,
 				       GType                      applet_type,
@@ -2378,6 +2657,15 @@ panel_applet_factory_setup_in_process (const gchar               *factory_id,
 						    callback, user_data);
 }
 
+/**
+ * panel_applet_set_background_widget:
+ * @applet: a #PanelApplet.
+ * @widget: a #GtkWidget.
+ *
+ * Configure #PanelApplet to automatically draw the background of the applet on
+ * @widget. It is generally enough to call this function with @applet as
+ * @widget.
+ **/
 void
 panel_applet_set_background_widget (PanelApplet *applet,
 				    GtkWidget   *widget)
diff --git a/libpanel-applet/panel-applet.h b/libpanel-applet/panel-applet.h
index e2accaa..8ad64e1 100644
--- a/libpanel-applet/panel-applet.h
+++ b/libpanel-applet/panel-applet.h
@@ -30,6 +30,21 @@
 
 G_BEGIN_DECLS
 
+/**
+ * PanelAppletOrient:
+ * @PANEL_APPLET_ORIENT_UP: The #PanelApplet is on a horizontal panel, at the
+ * bottom of the screen. It is oriented towards the top of the screen.
+ * @PANEL_APPLET_ORIENT_DOWN: The #PanelApplet is on a horizontal panel, at the
+ * top of the screen. It is oriented towards the bottom of the screen.
+ * @PANEL_APPLET_ORIENT_LEFT: The #PanelApplet is on a vertical panel, at the
+ * right of the screen. It is oriented towards the left of the screen.
+ * @PANEL_APPLET_ORIENT_RIGHT: The #PanelApplet is on a vertical panel, at the
+ * left of the screen. It is oriented towards the right of the screen.
+ *
+ * Type defining the orientation of the applet. The values may seem backward
+ * (e.g. %PANEL_APPLET_ORIENT_RIGHT means the panel is on the left side), but
+ * this represents the direction the applet is oriented to.
+ **/
 typedef enum {
 	PANEL_APPLET_ORIENT_UP,
 	PANEL_APPLET_ORIENT_DOWN,
@@ -44,6 +59,23 @@ typedef enum {
 #define PANEL_IS_APPLET_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), PANEL_TYPE_APPLET))
 #define PANEL_APPLET_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), PANEL_TYPE_APPLET, PanelAppletClass))
 
+/**
+ * PanelAppletFlags:
+ * @PANEL_APPLET_FLAGS_NONE: No flags set.
+ * @PANEL_APPLET_EXPAND_MAJOR: On horizontal panels, the #PanelApplet will be
+ * allocated as much width as possible. On vertical panels, it will be
+ * allocated as much height as possible.
+ * @PANEL_APPLET_EXPAND_MINOR: On horizontal panels, the #PanelApplet will be
+ * allocated the full height of the panel. On vertical panels, it will be
+ * allocated the full width. Most applets should set this flag in order to use
+ * the full panel size and allow the applet to be Fitt's Law compliant.
+ * @PANEL_APPLET_HAS_HANDLE: The panel will draw a handle for the
+ * #PanelApplet. This handle will be usable to move the applet, and to open the
+ * context menu of the applet.
+ *
+ * Flags to be used with panel_applet_get_flags()/panel_applet_set_flags(), to
+ * indicate to the panel a specific behavior requested by the #PanelApplet.
+ **/
 typedef enum {
 	PANEL_APPLET_FLAGS_NONE   = 0,
 	PANEL_APPLET_EXPAND_MAJOR = 1 << 0,
@@ -55,6 +87,20 @@ typedef struct _PanelApplet        PanelApplet;
 typedef struct _PanelAppletClass   PanelAppletClass;
 typedef struct _PanelAppletPrivate PanelAppletPrivate;
 
+/**
+ * PanelAppletFactoryCallback:
+ * @applet: a newly-created #PanelApplet.
+ * @iid: identifier of the requested applet type.
+ * @user_data: user data.
+ *
+ * The type used for callbacks after. The callback will usually check that @iid
+ * is a valid applet type identifier for the applet factory, and will then fill
+ * @applet with widgets, connect to signals, etc.
+ *
+ * Returns: %TRUE if @iid is a valid applet type identifier for the applet
+ * factory and if the creation of @applet was successfully completed, %FALSE
+ * otherwise.
+ **/
 typedef gboolean (*PanelAppletFactoryCallback) (PanelApplet *applet,
 						const gchar *iid,
 						gpointer     user_data);
@@ -150,6 +196,28 @@ int                panel_applet_factory_setup_in_process (const gchar
 	} while (0)
 #endif /* !defined(ENABLE_NLS) */
 
+/**
+ * PANEL_APPLET_OUT_PROCESS_FACTORY:
+ * @id: identifier of an applet factory.
+ * @type: GType of the applet this factory creates.
+ * @callback: (scope call): callback to be called when a new applet is created.
+ * @data: (closure): callback data.
+ *
+ * Convenience macro providing a main() function for an out-of-process applet.
+ * Internally, it will call panel_applet_factory_main() to create the
+ * @factory_id applet factory.
+ *
+ * Applet instances created by the applet factory will use @applet_type as
+ * GType. Unless you subclass #PanelApplet, you should use %PANEL_TYPE_APPLET
+ * as @applet_type.
+ *
+ * On creation of the applet instances, @callback is called to setup the
+ * applet. If @callback returns %FALSE, the creation of the applet instance is
+ * cancelled.
+ *
+ * It can only be used once, and is incompatible with the use of
+ * %PANEL_APPLET_IN_PROCESS_FACTORY and panel_applet_factory_main().
+ **/
 #define PANEL_APPLET_OUT_PROCESS_FACTORY(id, type, callback, data)		\
 int main (int argc, char *argv [])						\
 {										\
@@ -182,6 +250,27 @@ int main (int argc, char *argv [])						\
 	return retval;								\
 }
 
+/**
+ * PANEL_APPLET_IN_PROCESS_FACTORY:
+ * @id: identifier of an applet factory.
+ * @type: GType of the applet this factory creates.
+ * @callback: (scope call): callback to be called when a new applet is created.
+ * @data: (closure): callback data.
+ *
+ * Convenience macro providing the symbol needed to automatically register the
+ * @factory_id applet factory for an in-process applet.
+ *
+ * Applet instances created by the applet factory will use @applet_type as
+ * GType. Unless you subclass #PanelApplet, you should use %PANEL_TYPE_APPLET
+ * as @applet_type.
+ *
+ * On creation of the applet instances, @callback is called to setup the
+ * applet. If @callback returns %FALSE, the creation of the applet instance is
+ * cancelled.
+ *
+ * It can only be used once, and is incompatible with the use of
+ * %PANEL_APPLET_OUT_PROCESS_FACTORY and panel_applet_factory_main().
+ **/
 #define PANEL_APPLET_IN_PROCESS_FACTORY(id, type, callback, data)		\
 gboolean _panel_applet_shlib_factory (void);					\
 G_MODULE_EXPORT gint                                                            \
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]