--- a/src/hbcore/indicatorplugins/hbindicatorplugininterface.cpp	Mon Oct 04 17:49:30 2010 +0300
+++ b/src/hbcore/indicatorplugins/hbindicatorplugininterface.cpp	Mon Oct 18 18:23:13 2010 +0300
@@ -27,38 +27,81 @@
 
 /*!
     \class HbIndicatorPluginInterface
-    \brief HbIndicatorPluginInterface is an abstract base class for indicator plugins.
+    \brief HbIndicatorPluginInterface is an abstract interface class for indicator plugins.
+
+    Indicators are activated, deactivated and updated using HbIndicator class. Indicator
+    framework takes care of displaying indicators in satus bar and/or indicator menu.
+
+    Indicator plugins contain implentation of indicators. Single pluging can implement
+    one or several indicators. HbIndicatorInterface defines functionality required from an
+    indicator implementation.
+
+    Indicators are identified by a string. By convention the string should follow
+    inverted domain name format. For example com.nokia.hb.indicator.xxx/1.0.
+    Function indicatorTypes() returns a list of indicators the plugin implements.
 
-    Indicators are displayed in the status indicator area and/or in universal indicator popup.
-    Applications can create own indicators by implementing this plugin interface and creating
-    at least one class inherited from HbIndicatorInterface.
+    Appending version number into indicator type string enables versioning.
+    A plugin should handle versioning by returning indicator type string for all versions it
+    implements in indicatorTypes() and then in createIndicator() create an indicator
+    instance compatible with the version requested. This could always be the latest version if it
+    is backwards compatible with older versions. Indicator framework is unaware of version
+    numbers in type strings. It performs string comparison of the whole string when searching
+    for a plugin.
+
+    Plugins are responsible for maintaining system security for their own part. If plugin
+    performs operations that may compromise security or want's to limit access to specific
+    clients, it should check client security credentials in accessAllowed() function.
+    Indicator framework calls this function before activating/deactivating indicators.
+
+    \section _exceptions Exception handling
 
-    One plugin can implement one or more indicators. Indicators are identified by a type string.
-    The indicator types the plugin implements must be returned from the function
-    indicatorTypes(). The indicator is created, when requested by the client,
-    using createIndicator().
+    Indicator service uses two strategies in exception handling: Avoidance and trapping.
+    Memory allocation exceptions while an indicator is running are avoided by ensuring there is
+    sufficient heap space available before allowing new indicators to be activated.
+    Trapping is used while an indicator is created. A call to createIndicator() is enclosed
+    in try/catch block. Memory allocation exception causes indicator activation to fail
+    and an error is returned to a client. Plugin should take care there are no memory leaks
+    if exception is thrown inside createIndicator(). Calls to HbIndicatorInterface
+    functions are trapped and thrown allocation exceptions are ignored. Plugins can
+    provide more fine grained exception handling by trapping exceptions themselves.
+
+    \section _platform_hbindicatorplugin Platform-specific implementation notes for HbIndicatorPluginInterface
+
+    \subsection _nonsymbian Non-Symbian
 
-    Indicator plugin may limit access to an indicator. Before activating or deactivating an
-    indicator, the framework calls accessAllowed() allowing the plugin to inspect client's security
-    credentials. By returning false, the plugin denies client access.
+    Indicator plugins are loaded into client process. Plugin executables are searched from
+    application's current directory and HB_PLUGINS_DIR/indicators directory.
+
+    \subsection _symbian Symbian
+
+    Plugins are run by a server with platform security capabilities ProtServ, SwEvent,
+    TrustedUI and ReadDeviceData. If a plugin doesn't have required platform security
+    capabilities it will not load.
 
-    Plugins are loaded by a Device Dialog server. For information on installing plugins, refer to
-    HbDeviceDialogPlugin documentation.
+    Device dialog plugin stubs (.qtplugin) are searched from /resource/plugins/indicators directory
+    and executables in /sys/bin directory in each drive.
 
-    here's an example of how to create a simple indicator plugin.
-    If plugin implements only one indicator, the pluginInterface class can also inherit from
+    \section _example_code Example code
+
+    Below is an example of how to create a simple indicator plugin.
+
+    If plugin implements only one indicator, plugin can also inherit from
     HbIndicatorInterface. Example header-file:
 
-    \snippet{unit\unittest_hbindicator\codesnippetplugin\hbcodesnippetplugin.h,1}
+    \snippet{tsrc\unit\unittest_hbindicator\codesnippetplugin\hbcodesnippetplugin.h,1}
 
     Example source-file:
-    \snippet{unit\unittest_hbindicator\codesnippetplugin\hbcodesnippetplugin.cpp,1}
+    \snippet{tsrc\unit\unittest_hbindicator\codesnippetplugin\hbcodesnippetplugin.cpp,1}
+
+    If more than one indicators are implemented inside a plugin, plugin inherits from HbIndicatorPluginInterface.
+
+    \snippet{tsrc\unit\unittest_hbindicator\codesnippetplugin\hbcodesnippetplugin.h,2}
 
-    If more than one indicators are implemented inside a plugin, createIndicator should create new object
-    based on HbIndicatorInterface.
-    \snippet{unit\unittest_hbindicator\codesnippetplugin\hbcodesnippetplugin.cpp,2}
+    And createIndicator should create new object based on indicator type.
 
-    \sa HbIndicator, HbIndicatorInterface, HbDeviceDialogPlugin
+    \snippet{tsrc\unit\unittest_hbindicator\codesnippetplugin\hbcodesnippetplugin.cpp,2}
+
+    \sa HbIndicator, HbIndicatorInterface
 
     \stable
     \hbcore
@@ -67,7 +110,7 @@
 /*!
     \fn virtual QStringList HbIndicatorPluginInterface::indicatorTypes() const = 0
 
-    Should return the indicator types this plugin implements.
+    Should return the indicator types the plugin implements.
 */
 
 /*!
@@ -88,12 +131,15 @@
 
 /*!
     \fn virtual  HbIndicatorInterface *HbIndicatorPluginInterface::createIndicator(const QString &indicatorType) = 0
-    creates an indicator of type \a indicatorType. Ownership is passed to the caller.
+
+    Creates an indicator of type \a indicatorType. Ownership is passed to the caller.
+
     \sa HbIndicatorPluginInterface::indicatorTypes()
 */
 
 /*!
     \fn virtual int HbIndicatorPluginInterface::error() const = 0
+
     Returns the last error code. The code is cleared when any other API function than error() is
     called.
 */