diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java
index e3f4bc6..cc1b667 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/Extender.java
@@ -43,12 +43,22 @@
 
 /**
  * iPOJO Extender.
- * Looks for iPOJO Bundle and start the management of these bundles if needed.
+ * This class listens bundle arrivals and departures in order to detect and manage
+ * iPOJO powered bundles. This class creates factories and ask for instance creation.
+ * @see SynchronousBundleListener
+ * @see BundleActivator
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Extender implements SynchronousBundleListener, BundleActivator {
 
     /**
+     * Enables the iPOJO internal dispatcher.
+     * This internal dispatcher helps the OSGi framework to support large
+     * scale applications. The internal dispatcher is disabled by default.
+     */
+    protected static final boolean DISPATCHER_ENABLED = false;
+    
+    /**
      * iPOJO Component Type and Instance declaration header.
      */
     private static final String IPOJO_HEADER = "iPOJO-Components";
@@ -59,46 +69,53 @@
     private static final String IPOJO_EXTENSION = "IPOJO-Extension";
 
     /**
-     * iPOJO Extender logger.
+     * The iPOJO Extender logger.
      */
     private Logger m_logger;
 
     /**
-     * iPOJO Bundle Context.
+     * The Bundle Context of the iPOJO Core bundle.
      */
     private BundleContext m_context;
 
     /**
-     * Declared instance manager.
+     * The instance creator used to create instances.
+     * (Singleton)
      */
     private InstanceCreator m_creator;
 
     /**
-     * iPOJO Bundle.
+     * The iPOJO Bundle.
      */
     private Bundle m_bundle;
 
     /**
-     * List of factory types.
+     * The list of factory types.
      */
     private List m_factoryTypes = new ArrayList();
 
     /**
-     * List of unbound types.
+     * The list of unbound types.
+     * A type is unbound if the matching extension is not deployed.
      */
     private final List m_unboundTypes = new ArrayList();
     
     /**
-     * Thread analyzing arriving bundles and creating iPOJO contributions.
+     * The thread analyzing arriving bundles and creating iPOJO contributions.
      */
     private final CreatorThread m_thread = new CreatorThread();
+    
+    /**
+     * The internal iPOJO dispatcher.
+     */
+    private EventDispatcher m_dispatcher;
 
     /**
      * Bundle Listener Notification.
-     * @param event : the bundle event.
+     * @param event the bundle event.
      * @see org.osgi.framework.BundleListener#bundleChanged(org.osgi.framework.BundleEvent)
      */
-    public synchronized void bundleChanged(BundleEvent event) {
+    public synchronized void bundleChanged(final BundleEvent event) {
         if (event.getBundle() == m_bundle) { return; }
 
         switch (event.getType()) {
@@ -117,8 +134,11 @@
     }
 
     /**
-     * Ends the iPOJO Management for the given bundle.
-     * @param bundle : the bundle.
+     * Ends the iPOJO Management for the given bundle. 
+     * Generally the bundle is leaving. This method
+     * stops every factories declared is the bundle and 
+     * disposed every declared instances.
+     * @param bundle the bundle.
      */
     private void closeManagementFor(Bundle bundle) {
         List toRemove = new ArrayList();
@@ -168,8 +188,9 @@
     }
 
     /**
-     * Check if the given bundle is an iPOJO bundle, and begin the iPOJO management is true.
-     * @param bundle : the bundle to check.
+     * Checks if the given bundle is an iPOJO bundle, and begin 
+     * the iPOJO management is true.
+     * @param bundle the bundle to check.
      */
     private void startManagementFor(Bundle bundle) {
         Dictionary dict = bundle.getHeaders();
@@ -193,9 +214,10 @@
     }
 
     /**
-     * Parse an IPOJO-Extension manifest header.
-     * @param bundle : bundle containing the header.
-     * @param header : header to parse.
+     * Parses an IPOJO-Extension manifest header and then creates
+     * iPOJO extensions (factory types).
+     * @param bundle the bundle containing the header.
+     * @param header the header to parse.
      */
     private void parseAbstractFactoryType(Bundle bundle, String header) {
         String[] arr = ParseUtils.split(header, ",");
@@ -224,11 +246,13 @@
     }
 
     /**
-     * Parse the internal metadata (from the manifest (in the iPOJO-Components property)).
-     * @param bundle : the owner bundle.
-     * @param components : iPOJO Header String.
-     * @throws IOException : the manifest could not be found
-     * @throws ParseException : the parsing process failed
+     * Parses the internal metadata (from the manifest 
+     * (in the iPOJO-Components property)). This methods
+     * creates factories and add instances to the instance creator.
+     * @param bundle the owner bundle.
+     * @param components The iPOJO Header String.
+     * @throws IOException if the manifest can not be found
+     * @throws ParseException if the parsing process failed
      */
     private void parse(Bundle bundle, String components) throws IOException, ParseException {
         ManifestMetadataParser parser = new ManifestMetadataParser();
@@ -246,8 +270,8 @@
     }
 
     /**
-     * iPOJO Starting method.
-     * @param context : iPOJO bundle context.
+     * iPOJO Start method.
+     * @param context the iPOJO bundle context.
      * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
      */
     public void start(BundleContext context) {
@@ -256,6 +280,9 @@
         m_creator = new InstanceCreator(context);
 
         m_logger = new Logger(m_context, "IPOJO-Extender");
+        
+        m_dispatcher = new EventDispatcher(context);
+        m_dispatcher.start();
 
         // Begin by initializing core handlers
         startManagementFor(m_bundle);
@@ -275,13 +302,14 @@
     }
 
     /**
-     * Stop the iPOJO Management.
-     * @param context : bundle context.
+     * Stops the iPOJO Bundle.
+     * @param context the bundle context.
      * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
      */
     public void stop(BundleContext context) {
         m_thread.stop(); // Stop the thread processing bundles.
         m_context.removeBundleListener(this);
+        m_dispatcher.stop();
 
         for (int k = 0; k < m_factoryTypes.size(); k++) {
             ManagedAbstractFactoryType mft = (ManagedAbstractFactoryType) m_factoryTypes.get(k);
@@ -305,9 +333,9 @@
     }
 
     /**
-     * Add a component factory to the factory list.
-     * @param metadata : the new component metadata.
-     * @param bundle : the bundle.
+     * Adds a component factory to the factory list.
+     * @param metadata the new component metadata.
+     * @param bundle the bundle.
      */
     private void createAbstractFactory(Bundle bundle, Element metadata) {
         ManagedAbstractFactoryType factoryType = null;
@@ -376,30 +404,30 @@
      */
     private final class ManagedAbstractFactoryType {
         /**
-         * Type (i.e.) name of the extension.
+         * The type (i.e.) name of the extension.
          */
         String m_type;
 
         /**
-         * Abstract Factory class.
+         * The abstract Factory class.
          */
         Class m_clazz;
 
         /**
-         * Bundle object containing the declaration of the extension.
+         * The bundle object containing the declaration of the extension.
          */
         Bundle m_bundle;
 
         /**
-         * Factories created by this extension. 
+         * The factories created by this extension. 
          */
         private Map m_created;
 
         /**
-         * Constructor.
-         * @param factory : abstract factory class.
-         * @param type : name of the extension.
-         * @param bundle : bundle declaring the extension.
+         * Creates a ManagedAbstractFactoryType.
+         * @param factory the abstract factory class.
+         * @param type the name of the extension.
+         * @param bundle the bundle declaring the extension.
          */
         protected ManagedAbstractFactoryType(Class factory, String type, Bundle bundle) {
             m_bundle = bundle;
@@ -409,30 +437,30 @@
     }
 
     /**
-     * Structure storing unbound component type declaration.
-     * Unbound means that there is no extension able to manage it.
+     * Structure storing unbound component type declarations.
+     * Unbound means that there is no extension able to manage the extension.
      */
     private final class UnboundComponentType {
         /**
-         * Component type description.
+         * The component type description.
          */
         private final Element m_description;
 
         /**
-         * Bundle declaring this type.
+         * The bundle declaring this type.
          */
         private final Bundle m_bundle;
 
         /**
-         * Required extension name.
+         * The required extension name.
          */
         private final String m_type;
 
         /**
-         * Constructor.
-         * @param description : description of the component type.
-         * @param bundle : bundle declaring this type.
-         * @param type : required extension name.
+         * Creates a UnboundComponentType.
+         * @param description the description of the component type.
+         * @param bundle the bundle declaring this type.
+         * @param type the required extension name.
          */
         protected UnboundComponentType(String type, Element description, Bundle bundle) {
             m_type = type;
@@ -442,8 +470,8 @@
     }
 
     /**
-     * Compute the bundle context from the bundle class by introspection.
-     * @param bundle : bundle.
+     * Computes the bundle context from the bundle class by introspection.
+     * @param bundle the bundle.
      * @return the bundle context object or null if not found.
      */
     public BundleContext getBundleContext(Bundle bundle) {
@@ -513,7 +541,7 @@
     
 
     /**
-     * The creator thread analyze arriving bundle to create iPOJO contribution.
+     * The creator thread analyzes arriving bundles to create iPOJO contribution.
      */
     private class CreatorThread implements Runnable {
 
@@ -523,14 +551,14 @@
         private boolean m_started = true;
         
         /**
-         * List of bundle that are going to be analyzed.
+         * The list of bundle that are going to be analyzed.
          */
         private List m_bundles = new ArrayList();
         
         /**
-         * A bundle is arrived.
+         * A bundle is arriving.
          * This method is synchronized to avoid concurrent modification of the waiting list.
-         * @param bundle : new bundle
+         * @param bundle the new bundle
          */
         public synchronized void addBundle(Bundle bundle) {
             m_bundles.add(bundle);
@@ -542,14 +570,14 @@
          * A bundle is leaving.
          * If the bundle was not already processed, the bundle is remove from the waiting list.
          * This method is synchronized to avoid concurrent modification of the waiting list.
-         * @param bundle : the leaving bundle.
+         * @param bundle the leaving bundle.
          */
         public synchronized void removeBundle(Bundle bundle) {
             m_bundles.remove(bundle);
         }
         
         /**
-         * Stop the creator thread.
+         * Stops the creator thread.
          */
         public synchronized void stop() {
             m_started = false;
@@ -558,10 +586,10 @@
         }
 
         /**
-         * Creator thread run method.
-         * While the waiting list is not empty, the thread launch the bundle analyzing.
+         * Creator thread's run method.
+         * While the list is not empty, the thread launches the bundle analyzing on the next bundle.
          * When the list is empty, the thread sleeps until the arrival of a new bundle 
-         * or that iPOJO stops.
+         * or until iPOJO stops.
          * @see java.lang.Runnable#run()
          */
         public void run() {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java
index 09bfcdf..61e549c 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoContext.java
@@ -26,6 +26,7 @@
 import org.osgi.framework.BundleContext;
 import org.osgi.framework.BundleException;
 import org.osgi.framework.BundleListener;
+import org.osgi.framework.Constants;
 import org.osgi.framework.Filter;
 import org.osgi.framework.FrameworkListener;
 import org.osgi.framework.InvalidSyntaxException;
@@ -36,45 +37,61 @@
 /**
  * The iPOJO Context is a BundleContext implementation allowing the separation
  * between Bundle context and Service (Bundle) Context.
- * 
+ * This is used inside composition to differentiate the classloading context (i.e.
+ * Bundle) and the service registry access.
+ * This class delegates calls to the good internal context (either the BundleContext
+ * or the ServiceContext) according to the method. If the instance does not have a valid
+ * service context, the bundle context is always used. 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class IPojoContext implements BundleContext, ServiceContext {
 
     /**
-     * BundleContext used to access bundle method.
+     * The bundleContext used to access bundle methods.
      */
     private BundleContext m_bundleContext;
 
     /**
-     * Service Context used to access service interaction.
+     * The service context used to access to the service registry.
      */
     private ServiceContext m_serviceContext;
+    
+    /**
+     * The internal event dispatcher used to avoid the multiplication
+     * of service listeners. The dispatcher is only used when the service context is
+     * not specified and if the internal dispatching is enabled ({@link Extender#DISPATCHER_ENABLED}
+     */
+    private EventDispatcher m_dispatcher;
 
     /**
-     * Constructor. Used when the service context = the bundle context
-     * 
-     * @param context : bundle context
+     * Creates an iPOJO Context.
+     * No service context is specified.
+     * This constructor is used when the
+     * instance lives in the global context.
+     * @param context the bundle context
      */
     public IPojoContext(BundleContext context) {
         m_bundleContext = context;
+        m_dispatcher = EventDispatcher.getDispatcher();
     }
 
     /**
-     * Constructor. Used when the service context and the bundle context are
-     * different
-     * 
-     * @param bundleContext : bundle context
-     * @param serviceContext : service context
+     * Creates an iPOJO Context.
+     * A service context is used to refer to the
+     * service registry. The service context will be 
+     * used for all service accesses.
+     * @param bundleContext the bundle context
+     * @param serviceContext the service context
      */
     public IPojoContext(BundleContext bundleContext, ServiceContext serviceContext) {
         m_bundleContext = bundleContext;
         m_serviceContext = serviceContext;
+        m_dispatcher = EventDispatcher.getDispatcher();
     }
 
     /**
-     * Add a bundle listener.
-     * @param listener : the listener to add
+     * Adds a bundle listener.
+     * @param listener the listener to add
      * @see org.osgi.framework.BundleContext#addBundleListener(org.osgi.framework.BundleListener)
      */
     public void addBundleListener(BundleListener listener) {
@@ -82,8 +99,8 @@
     }
 
     /**
-     * Add a framework listener.
-     * @param listener : the listener object to add
+     * Adds a framework listener.
+     * @param listener the listener object to add
      * @see org.osgi.framework.BundleContext#addFrameworkListener(org.osgi.framework.FrameworkListener)
      */
     public void addFrameworkListener(FrameworkListener listener) {
@@ -91,15 +108,30 @@
     }
 
     /**
-     * Add a service listener.
-     * @param listener : the service listener to add.
-     * @param filter : the LDAP filter
-     * @throws InvalidSyntaxException : occurs when the LDAP filter is malformed
+     * Adds a service listener.
+     * This methods registers the listener on the service context
+     * if it specified. Otherwise, if the internal dispatcher is enabled,
+     * it registers the listener inside the internal dispatcher (if
+     * the filter match against the iPOJO Filter format 
+     * {@link IPojoContext#match(String)}). Finally, if the internal 
+     * dispatcher is disabled, it uses the "regular" bundle context.
+     * @param listener the service listener to add.
+     * @param filter the LDAP filter
+     * @throws InvalidSyntaxException if LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)
      */
     public void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException {
         if (m_serviceContext == null) {
-            m_bundleContext.addServiceListener(listener, filter);
+            if (Extender.DISPATCHER_ENABLED) {
+                String itf = match(filter);
+                if (itf != null) {
+                    m_dispatcher.addListener(itf, listener);
+                } else {
+                    m_bundleContext.addServiceListener(listener, filter);
+                }
+            } else {
+                m_bundleContext.addServiceListener(listener, filter);
+            }
         } else {
             m_serviceContext.addServiceListener(listener, filter);
         }
@@ -107,7 +139,9 @@
 
     /**
      * Add a service listener.
-     * @param listener : the service listener to add.
+     * This methods registers the listener on the service context
+     * if it specified. Otherwise, it uses the "regular" bundle context.
+     * @param listener the service listener to add.
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener)
      */
     public void addServiceListener(ServiceListener listener) {
@@ -117,12 +151,31 @@
             m_serviceContext.addServiceListener(listener);
         }
     }
+    
+    /**
+     * This method checks if the filter matches with the iPOJO
+     * filter format: <code>(OBJECTCLASS=$ITF)</code>. It tries
+     * to extract the required interface (<code>$ITF</code>).
+     * @param filter the filter to analyze
+     * @return the required interface or <code>null</code>
+     * if the filter doesn't match with the iPOJO format.
+     */
+    private String match(String filter) {
+        if (filter != null && filter.startsWith("(" + Constants.OBJECTCLASS + "=") // check the beginning (OBJECTCLASS
+            && filter.lastIndexOf(')') == filter.indexOf(')')) { // check that there is only one )
+            return filter.substring(("(" + Constants.OBJECTCLASS + "=").length(), filter.length() - 1);
+        }
+        return null;
+    }
+    
+    
 
     /**
-     * Create a Filter object.
-     * @param filter : the string form of the LDAP filter to create
-     * @return the Filter object.
-     * @throws InvalidSyntaxException : occurs when the given filter is malformed
+     * Creates a filter objects.
+     * This method always uses the bundle context.
+     * @param filter the string form of the LDAP filter to create
+     * @return the filter object.
+     * @throws InvalidSyntaxException if the given filter is malformed
      * @see org.osgi.framework.BundleContext#createFilter(java.lang.String)
      */
     public Filter createFilter(String filter) throws InvalidSyntaxException {
@@ -130,11 +183,13 @@
     }
 
     /**
-     * Get the service references matching with the given query.
-     * @param clazz : Required interface
-     * @param filter : LDAP filter
-     * @return the array of available service reference
-     * @throws InvalidSyntaxException : occurs if the LDAP filter is malformed
+     * Gets the service references matching with the given query.
+     * Uses the service context if specified, used the bundle context
+     * otherwise.
+     * @param clazz the required interface
+     * @param filter the LDAP filter
+     * @return the array of available service references
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#getAllServiceReferences(java.lang.String, java.lang.String)
      */
     public ServiceReference[] getAllServiceReferences(String clazz, String filter) throws InvalidSyntaxException {
@@ -146,8 +201,9 @@
     }
 
     /**
-     * Get the current bundle.
-     * @return the current bundle
+     * Gets the current bundle object.
+     * @return the bundle declaring the component type of the instance
+     * using the current IPojoContext.
      * @see org.osgi.framework.BundleContext#getBundle()
      */
     public Bundle getBundle() {
@@ -155,8 +211,8 @@
     }
 
     /**
-     * Get the bundle object with the given id.
-     * @param bundleId : bundle id
+     * Gets the bundle object with the given id.
+     * @param bundleId the bundle id
      * @return the bundle object
      * @see org.osgi.framework.BundleContext#getBundle(long)
      */
@@ -165,7 +221,7 @@
     }
 
     /**
-     * Get installed bundles.
+     * Gets installed bundles.
      * @return the list of installed bundles
      * @see org.osgi.framework.BundleContext#getBundles()
      */
@@ -174,8 +230,8 @@
     }
 
     /**
-     * Get a data file.
-     * @param filename : File name.
+     * Gets a data file.
+     * @param filename the file name.
      * @return the File object
      * @see org.osgi.framework.BundleContext#getDataFile(java.lang.String)
      */
@@ -184,9 +240,10 @@
     }
 
     /**
-     * Get a property value.
-     * @param key : key of the asked property
-     * @return the property value (object) or null if no property are associated with the given key
+     * Gets a property value.
+     * @param key the key of the asked property
+     * @return the property value (object) or <code>null</code> if no
+     * property are associated with the given key
      * @see org.osgi.framework.BundleContext#getProperty(java.lang.String)
      */
     public String getProperty(String key) {
@@ -194,9 +251,14 @@
     }
 
     /**
-     * Get a service object.
-     * @param reference : the required service reference 
-     * @return the service object or null if the service reference is no more valid or if the service object is not accessible
+     * Gets a service object.
+     * The given service reference must come from the same context than
+     * where the service is get.
+     * This method uses the service context if specified, the bundle
+     * context otherwise.
+     * @param reference the required service reference 
+     * @return the service object or <code>null</code> if the service reference 
+     * is no more valid or if the service object is not accessible.
      * @see org.osgi.framework.BundleContext#getService(org.osgi.framework.ServiceReference)
      */
     public Object getService(ServiceReference reference) {
@@ -208,9 +270,12 @@
     }
 
     /**
-     * Get a service reference for the given interface.
-     * @param clazz : the required interface name
-     * @return a service reference on a available provider or null if no provider available
+     * Gets a service reference for the given interface.
+     * This method uses the service context if specified, the bundle
+     * context otherwise.
+     * @param clazz the required interface name
+     * @return a service reference on a available provider or <code>null</code>
+     * if no providers available
      * @see org.osgi.framework.BundleContext#getServiceReference(java.lang.String)
      */
     public ServiceReference getServiceReference(String clazz) {
@@ -222,11 +287,14 @@
     }
 
     /**
-     * Get service reference list for the given query.
-     * @param clazz : the name of the required service interface
-     * @param filter : LDAP filter to apply on service provider
-     * @return : the array of consistent service reference or null if no available provider
-     * @throws InvalidSyntaxException : occurs if the LDAP filter is malformed
+     * Gets service reference list for the given query.
+     * This method uses the service context if specified, the bundle
+     * context otherwise.
+     * @param clazz the name of the required service interface
+     * @param filter the LDAP filter to apply on service provider
+     * @return the array of consistent service reference or <code>null</code>
+     * if no available providers
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#getServiceReferences(java.lang.String, java.lang.String)
      */
     public ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException {
@@ -238,10 +306,10 @@
     }
 
     /**
-     * Install a bundle.
-     * @param location : URL of the bundle to install
+     * Installs a bundle.
+     * @param location the URL of the bundle to install
      * @return the installed bundle
-     * @throws BundleException : if the bundle cannot be installed correctly
+     * @throws BundleException if the bundle cannot be installed correctly
      * @see org.osgi.framework.BundleContext#installBundle(java.lang.String)
      */
     public Bundle installBundle(String location) throws BundleException {
@@ -249,11 +317,11 @@
     }
 
     /**
-     * Install a bundle.
-     * @param location : URL of the bundle to install
-     * @param input : 
+     * Installs a bundle.
+     * @param location the URL of the bundle to install
+     * @param input the input stream to load the bundle.
      * @return the installed bundle
-     * @throws BundleException : if the bundle cannot be installed correctly
+     * @throws BundleException  if the bundle cannot be installed correctly
      * @see org.osgi.framework.BundleContext#installBundle(java.lang.String, java.io.InputStream)
      */
     public Bundle installBundle(String location, InputStream input) throws BundleException {
@@ -261,10 +329,13 @@
     }
 
     /**
-     * Register a service.
-     * @param clazzes : interfaces provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
+     * Registers a service.
+     * This method uses the service context if specified (and so, registers
+     * the service in this service registry), the bundle context otherwise (the
+     * service will be available to every global instances).
+     * @param clazzes the interfaces provided by the service.
+     * @param service the service object.
+     * @param properties the service properties to publish
      * @return the service registration for this service publication.
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
      */
@@ -277,10 +348,13 @@
     }
 
     /**
-     * Register a service.
-     * @param clazz : interface provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
+     * Registers a service.
+     * This method uses the service context if specified (and so, registers
+     * the service in this service registry), the bundle context otherwise (the
+     * service will be available to every global instances).
+     * @param clazz the interface provided by the service.
+     * @param service the the service object.
+     * @param properties the service properties to publish.
      * @return the service registration for this service publication.
      * @see org.osgi.framework.BundleContext#registerService(java.lang.String, java.lang.Object, java.util.Dictionary)
      */
@@ -293,8 +367,8 @@
     }
 
     /**
-     * Remove a bundle listener.
-     * @param listener : the listener to remove
+     * Removes a bundle listener.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeBundleListener(org.osgi.framework.BundleListener)
      */
     public void removeBundleListener(BundleListener listener) {
@@ -302,8 +376,8 @@
     }
 
     /**
-     * Remove a framework listener.
-     * @param listener : the listener to remove
+     * Removes a framework listener.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeFrameworkListener(org.osgi.framework.FrameworkListener)
      */
     public void removeFrameworkListener(FrameworkListener listener) {
@@ -311,23 +385,29 @@
     }
 
     /**
-     * Remove a service listener.
-     * @param listener : the service listener to remove
+     * Removes a service listener.
+     * Removes the service listener from where it was registered so either in
+     * the global context, or in the service context or in the internal dispatcher.
+     * @param listener the service listener to remove
      * @see org.apache.felix.ipojo.ServiceContext#removeServiceListener(org.osgi.framework.ServiceListener)
      * @see org.osgi.framework.BundleContext#removeServiceListener(org.osgi.framework.ServiceListener)
      */
     public void removeServiceListener(ServiceListener listener) {
         if (m_serviceContext == null) {
-            m_bundleContext.removeServiceListener(listener);
+            if (! Extender.DISPATCHER_ENABLED || ! m_dispatcher.removeListener(listener)) {
+                m_bundleContext.removeServiceListener(listener);
+            }
         } else {
             m_serviceContext.removeServiceListener(listener);
         }
     }
 
     /**
-     * Unget the service reference.
-     * @param reference : the reference to unget
-     * @return true if you are the last user of the reference
+     * Ungets the service reference.
+     * This method uses the service context if specified, 
+     * the bundle context otherwise.
+     * @param reference the reference to unget
+     * @return <code>true</code> if you are the last user of the reference
      * @see org.osgi.framework.BundleContext#ungetService(org.osgi.framework.ServiceReference)
      */
     public boolean ungetService(ServiceReference reference) {
@@ -339,7 +419,7 @@
     }
 
     /**
-     * Get the global context, i.e. the bundle context of the factory.
+     * Gets the global context, i.e. the bundle context of the factory.
      * @return the global bundle context.
      */
     public BundleContext getGlobalContext() {
@@ -347,8 +427,10 @@
     }
 
     /**
-     * Get the service context, i.e. the composite context.
-     * @return the service context.
+     * Gets the service context, i.e. the composite context.
+     * Returns <code>null</code> if the instance does not live
+     * inside a composite.
+     * @return the service context or <code>null</code>.
      */
     public ServiceContext getServiceContext() {
         return m_serviceContext;
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java
index a3840084..c1d725b 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/IPojoFactory.java
@@ -37,7 +37,10 @@
 import org.osgi.service.cm.ManagedServiceFactory;
 
 /**
- * This class abstracts iPOJO factories.
+ * This class defines common mechanisms of iPOJO component factories
+ * (i.e. component type).
+ * This class implements both the Factory and ManagedServiceFactory
+ * services.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public abstract class IPojoFactory implements Factory, ManagedServiceFactory {
@@ -47,22 +50,25 @@
      */
 
     /**
-     * List of the managed instance name. This list is shared by all factories.
+     * The list of the managed instance name.
+     * This list is shared by all factories and is
+     * used to assert name unicity.
      */
     protected static List m_instancesName = new ArrayList();
 
     /**
-     * Component-Type description exposed by the factory service.
+     * The component type description exposed by the {@link Factory} service.
      */
     protected ComponentTypeDescription m_componentDesc;
 
     /**
-     * List of the managed instance managers. The key of this map is the name (i.e. instance names) of the created instance
+     * The list of the managed instance managers. 
+     * The key of this map is the name (i.e. instance names) of the created instance
      */
     protected final Map m_componentInstances = new HashMap();
 
     /**
-     * Component Type provided by this factory.
+     * The component type metadata.
      */
     protected final Element m_componentMetadata;
 
@@ -72,56 +78,69 @@
     protected final BundleContext m_context;
 
     /**
-     * Factory Name. Could be the component class name if the factory name is not set.
+     * The factory name. 
+     * Could be the component class name if the factory name is not set.
      * Immutable once set.
      */
     protected String m_factoryName;
 
     /**
-     * List of required handler.
+     * The list of required handlers.
      */
     protected List m_requiredHandlers = new ArrayList();
 
     /**
-     * List of listeners.
+     * The list of factory state listeners.
+     * @see FactoryStateListener
      */
     protected List m_listeners = new ArrayList(1);
 
     /**
-     * Logger for the factory (and all component instance).
+     * The logger for the factory (and all component instances).
      */
     protected final Logger m_logger;
 
     /**
-     * Is the factory public (expose as a service).
+     * Is the factory public (exposed as services).
      */
     protected final boolean m_isPublic;
 
     /**
-     * Service Registration of this factory (Factory & ManagedServiceFactory).
+     * The service registration of this factory (Factory & ManagedServiceFactory).
+     * @see ManagedServiceFactory
+     * @see Factory
      */
     protected ServiceRegistration m_sr;
 
     /**
-     * Factory state.
+     * The factory state.
+     * Can be:
+     * <li>{@link Factory#INVALID}</li>
+     * <li>{@link Factory#VALID}</li>
+     * The factory is invalid at the beginning.
+     * A factory becomes valid if every required handlers
+     * are available (i.e. can be created).
      */
     protected int m_state = Factory.INVALID;
 
     /**
-     * Index used to generate instance name if not set.
+     * The index used to generate instance name if not set.
      */
     private long m_index = 0;
 
     /**
-     * Flag indicating if this factory has already a computed description or not.
+     * The flag indicating if this factory has already a 
+     * computed description or not.
      */
     private boolean m_described;
 
     /**
-     * Constructor.
-     * @param context : bundle context of the bundle containing the factory.
-     * @param metadata : description of the component type.
-     * @throws ConfigurationException occurs when the element describing the factory is malformed.
+     * Creates an iPOJO Factory.
+     * At the end of this method, the required set of handler is computed.
+     * But the result is computed by a sub-class.
+     * @param context the bundle context of the bundle containing the factory.
+     * @param metadata the description of the component type.
+     * @throws ConfigurationException if the element describing the factory is malformed.
      */
     public IPojoFactory(BundleContext context, Element metadata) throws ConfigurationException {
         m_context = context;
@@ -133,13 +152,17 @@
         m_requiredHandlers = getRequiredHandlerList(); // Call sub-class to get the list of required handlers.
     }
 
+    /**
+     * Gets the component type description.
+     * @return the component type description
+     */
     public ComponentTypeDescription getComponentTypeDescription() {
         return new ComponentTypeDescription(this);
     }
 
     /**
      * Adds a factory listener.
-     * @param listener : the factory listener to add.
+     * @param listener the factory listener to add.
      * @see org.apache.felix.ipojo.Factory#addFactoryStateListener(org.apache.felix.ipojo.FactoryStateListener)
      */
     public void addFactoryStateListener(FactoryStateListener listener) {
@@ -149,7 +172,7 @@
     }
 
     /**
-     * Gets the logger used by instances of he current factory.
+     * Gets the logger used by instances created by the current factory.
      * @return the factory logger.
      */
     public Logger getLogger() {
@@ -158,35 +181,38 @@
 
     /**
      * Computes the factory name.
+     * Each sub-type must override this method. 
      * @return the factory name.
      */
     public abstract String getFactoryName();
 
     /**
      * Computes the required handler list.
+     * Each sub-type must override this method.
      * @return the required handler list
      */
     public abstract List getRequiredHandlerList();
 
     /**
      * Creates an instance.
-     * This method is called with the lock.
-     * @param config : instance configuration
-     * @param context : ipojo context to use
-     * @param handlers : handler array to use
+     * This method is called with the monitor lock.
+     * @param config the instance configuration
+     * @param context the iPOJO context to use
+     * @param handlers the handler array to use
      * @return the new component instance.
-     * @throws ConfigurationException : occurs when the instance creation failed during the configuration process.
+     * @throws ConfigurationException if the instance creation failed during the configuration process.
      */
     public abstract ComponentInstance createInstance(Dictionary config, IPojoContext context, HandlerManager[] handlers)
             throws ConfigurationException;
 
     /**
-     * Creates an instance. The given configuration needs to contain the 'name' property.
-     * @param configuration : configuration of the created instance.
+     * Creates an instance.
+     * This method creates the instance in the global context.
+     * @param configuration the configuration of the created instance.
      * @return the created component instance.
-     * @throws UnacceptableConfiguration : occurs if the given configuration is not consistent with the component type of this factory.
-     * @throws MissingHandlerException : occurs if an handler is unavailable when the instance is created.
-     * @throws org.apache.felix.ipojo.ConfigurationException : occurs when the instance or type configuration are not correct.
+     * @throws UnacceptableConfiguration if the given configuration is not consistent with the component type of this factory.
+     * @throws MissingHandlerException if an handler is unavailable when the instance is created.
+     * @throws org.apache.felix.ipojo.ConfigurationException if the instance or type configuration are not correct.
      * @see org.apache.felix.ipojo.Factory#createComponentInstance(java.util.Dictionary)
      */
     public ComponentInstance createComponentInstance(Dictionary configuration) throws UnacceptableConfiguration, MissingHandlerException,
@@ -195,15 +221,17 @@
     }
 
     /**
-     * Creates an instance. The given configuration needs to contain the 'name' property.
+     * Creates an instance in the specified service context.
      * This method is synchronized to assert the validity of the factory during the creation.
-     * Callbacks to sub-class and to create instance need to be aware that they are holding the lock.
-     * @param configuration : configuration of the created instance.
-     * @param serviceContext : the service context to push for this instance.
+     * Callbacks to sub-class and  created instances need to be aware that they are holding the monitor lock.
+     * This method call the override {@link IPojoFactory#createInstance(Dictionary, IPojoContext, HandlerManager[])
+     * method.
+     * @param configuration the configuration of the created instance.
+     * @param serviceContext the service context to push for this instance.
      * @return the created component instance.
-     * @throws UnacceptableConfiguration : occurs if the given configuration is not consistent with the component type of this factory.
-     * @throws MissingHandlerException : occurs when an handler is unavailable when creating the instance.
-     * @throws org.apache.felix.ipojo.ConfigurationException : when the instance configuration failed.
+     * @throws UnacceptableConfiguration if the given configuration is not consistent with the component type of this factory.
+     * @throws MissingHandlerException if an handler is unavailable when creating the instance.
+     * @throws org.apache.felix.ipojo.ConfigurationException if the instance configuration failed.
      * @see org.apache.felix.ipojo.Factory#createComponentInstance(java.util.Dictionary)
      */
     public synchronized ComponentInstance createComponentInstance(Dictionary configuration, ServiceContext serviceContext) throws UnacceptableConfiguration, // NOPMD
@@ -262,6 +290,11 @@
         }
     }
 
+    /**
+     * Gets the bundle context of the factory.
+     * @return the bundle context of the factory.
+     * @see org.apache.felix.ipojo.Factory#getBundleContext()
+     */
     public BundleContext getBundleContext() {
         return m_context;
     }
@@ -275,7 +308,7 @@
 
     /**
      * Gets the component type description.
-     * @return the component type description object. Null if not already computed.
+     * @return the component type description object. <code>Null</code> if not already computed.
      */
     public synchronized ComponentTypeDescription getComponentDescription() {
         return m_componentDesc;
@@ -295,8 +328,8 @@
     }
 
     /**
-     * Computes the list of missing handlers. This method is called with the lock.
-     * @return list of missing handlers.
+     * Computes the list of missing handlers. This method is called with the monitor lock.
+     * @return the list of missing handlers.
      * @see org.apache.felix.ipojo.Factory#getMissingHandlers()
      */
     public List getMissingHandlers() {
@@ -324,7 +357,7 @@
      * Gets the list of required handlers.
      * This method is synchronized to avoid the concurrent modification
      * of the required handlers.
-     * @return list of required handlers.
+     * @return the list of required handlers.
      * @see org.apache.felix.ipojo.Factory#getRequiredHandlers()
      */
     public synchronized List getRequiredHandlers() {
@@ -348,8 +381,8 @@
 
     /**
      * Checks if the configuration is acceptable.
-     * @param conf : the configuration to test.
-     * @return true if the configuration is acceptable.
+     * @param conf the configuration to test.
+     * @return <code>true</code> if the configuration is acceptable.
      * @see org.apache.felix.ipojo.Factory#isAcceptable(java.util.Dictionary)
      */
     public boolean isAcceptable(Dictionary conf) {
@@ -365,9 +398,13 @@
 
     /**
      * Checks if the configuration is acceptable.
-     * @param conf : the configuration to test.
-     * @throws UnacceptableConfiguration occurs if the configuration is unacceptable.
-     * @throws MissingHandlerException occurs if an handler is missing.
+     * This method checks the following assertions:
+     * <li>All handlers can be creates</li>
+     * <li>The configuration does not override immutable properties</li>
+     * <li>The configuration contains a value for every unvalued property</li>
+     * @param conf the configuration to test.
+     * @throws UnacceptableConfiguration if the configuration is unacceptable.
+     * @throws MissingHandlerException if an handler is missing.
      */
     public void checkAcceptability(Dictionary conf) throws UnacceptableConfiguration, MissingHandlerException {
         PropertyDescription[] props;
@@ -395,10 +432,13 @@
 
     /**
      * Reconfigures an existing instance.
+     * The acceptability of the configuration is checked before the reconfiguration. Moreover,
+     * the configuration must contain the 'instance.name' property specifying the instance 
+     * to reconfigure.
      * This method is synchronized to assert the validity of the factory during the reconfiguration.
-     * @param properties : the new configuration to push.
-     * @throws UnacceptableConfiguration : occurs if the new configuration is not consistent with the component type.
-     * @throws MissingHandlerException : occurs if the current factory is not valid.
+     * @param properties the new configuration to push.
+     * @throws UnacceptableConfiguration if the new configuration is not consistent with the component type.
+     * @throws MissingHandlerException if the current factory is not valid.
      * @see org.apache.felix.ipojo.Factory#reconfigure(java.util.Dictionary)
      */
     public synchronized void reconfigure(Dictionary properties) throws UnacceptableConfiguration, MissingHandlerException {
@@ -422,7 +462,7 @@
 
     /**
      * Removes a factory listener.
-     * @param listener : the factory listener to remove.
+     * @param listener the factory listener to remove.
      * @see org.apache.felix.ipojo.Factory#removeFactoryStateListener(org.apache.felix.ipojo.FactoryStateListener)
      */
     public void removeFactoryStateListener(FactoryStateListener listener) {
@@ -432,13 +472,18 @@
     }
 
     /**
-     * Stopping method. This method is call when the factory is stopping.
+     * Stopping method. 
+     * This method is call when the factory is stopping.
      * This method is called when holding the lock on the factory.
      */
     public abstract void stopping();
 
     /**
      * Stops all the instance managers.
+     * This method calls the {@link IPojoFactory#stopping()} method,
+     * notifies listeners, and disposes created instances. Moreover,
+     * if the factory is public, services are also unregistered.
+     *  
      */
     public synchronized void stop() {
         ComponentInstance[] instances;
@@ -482,7 +527,8 @@
     }
 
     /**
-     * Destroys the factory. The factory cannot be restarted. Only the extender can call this method.
+     * Destroys the factory. 
+     * The factory cannot be restarted. Only the {@link Extender} can call this method.
      */
     synchronized void dispose() {
         stop(); // Does not hold the lock.
@@ -491,12 +537,17 @@
     }
 
     /**
-     * Starting method. This method is called when the factory is starting. This method is called when holding the lock on the factory.
+     * Starting method. 
+     * This method is called when the factory is starting.
+     * This method is called when holding the lock on the factory.
      */
     public abstract void starting();
 
     /**
      * Starts the factory.
+     * Tries to compute the component type description,
+     * calls the {@link IPojoFactory#starting()} method,
+     * and published services if the factory is public.
      */
     public synchronized void start() {
         if (m_described) { // Already started.
@@ -519,9 +570,9 @@
 
     /**
      * Creates or updates an instance.
-     * @param name : name of the instance
-     * @param properties : configuration of the instance
-     * @throws org.osgi.service.cm.ConfigurationException : if the configuration is not consistent for this component type
+     * @param name the name of the instance
+     * @param properties the new configuration of the instance
+     * @throws org.osgi.service.cm.ConfigurationException if the configuration is not consistent for this component type
      * @see org.osgi.service.cm.ManagedServiceFactory#updated(java.lang.String, java.util.Dictionary)
      */
     public void updated(String name, Dictionary properties) throws org.osgi.service.cm.ConfigurationException {
@@ -561,7 +612,7 @@
 
     /**
      * Deletes an instance.
-     * @param name : name of the instance to delete
+     * @param name the name of the instance to delete
      * @see org.osgi.service.cm.ManagedServiceFactory#deleted(java.lang.String)
      */
     public synchronized void deleted(String name) {
@@ -574,7 +625,7 @@
 
     /**
      * Callback called by instance when disposed.
-     * @param instance : the destroyed instance
+     * @param instance the destroyed instance
      */
     public void disposed(ComponentInstance instance) {
         String name = instance.getInstanceName();
@@ -585,7 +636,11 @@
     }
 
     /**
-     * Computes the component type description. The factory must be valid when calling this method.
+     * Computes the component type description.
+     * To do this, it creates a 'ghost' instance of the handler 
+     * and calls the {@link Handler#initializeComponentFactory(ComponentTypeDescription, Element)}
+     * method. The handler instance is then deleted. 
+     * The factory must be valid when calling this method.
      * This method is called with the lock.
      */
     protected void computeDescription() {
@@ -607,7 +662,10 @@
 
     /**
      * Computes factory state.
-     * This method is call when holding the lock on the current factory.
+     * The factory is valid if every required handler are available.
+     * If the factory becomes valid for the first time, the component
+     * type description is computed.
+     * This method is called when holding the lock on the current factory.
      */
     protected void computeFactoryState() {
         boolean isValid = true;
@@ -669,11 +727,11 @@
     }
 
     /**
-     * Checks if the given handler identifier and the service reference can match.
+     * Checks if the given handler identifier and the service reference match.
      * Does not need to be synchronized as the method does not use any fields.
-     * @param req : the handler identifier.
-     * @param ref : the service reference.
-     * @return true if the service reference can fulfill the handler requirement
+     * @param req the handler identifier.
+     * @param ref the service reference.
+     * @return <code>true</code> if the service reference can fulfill the handler requirement
      */
     protected boolean match(RequiredHandler req, ServiceReference ref) {
         String name = (String) ref.getProperty(Handler.HANDLER_NAME_PROPERTY);
@@ -685,11 +743,12 @@
     }
 
     /**
-     * Returns the handler object for the given required handler. The handler is instantiated in the given service context.
+     * Returns the handler object for the given required handler.
+     * The handler is instantiated in the given service context.
      * This method is called with the lock.
-     * @param req : handler to create.
-     * @param context : service context in which create the handler (instance context).
-     * @return the Handler object.
+     * @param req the handler to create.
+     * @param context the service context in which the handler is created (same as the instance context).
+     * @return the handler object.
      */
     protected HandlerManager getHandler(RequiredHandler req, ServiceContext context) {
         try {
@@ -716,9 +775,9 @@
     }
 
     /**
-     * Helping method generating a new unique name.
+     * Helper method generating a new unique name.
      * This method is call when holding the lock to assert generated name unicity.
-     * @return an non already used name
+     * @return a non already used name
      */
     protected String generateName() {
         String name = m_factoryName + "-" + m_index;
@@ -736,34 +795,34 @@
      */
     protected class RequiredHandler implements Comparable {
         /**
-         * Factory to create this handler.
+         * The factory to create this handler.
          */
         private HandlerFactory m_factory;
 
         /**
-         * Handler name.
+         * The handler name.
          */
         private final String m_name;
 
         /**
-         * Handler start level.
+         * The handler start level.
          */
         private int m_level = Integer.MAX_VALUE;
 
         /**
-         * Handler namespace.
+         * The handler namespace.
          */
         private final String m_namespace;
 
         /**
-         * Service Reference of the handler factory.
+         * The Service Reference of the handler factory.
          */
         private ServiceReference m_reference;
 
         /**
-         * Constructor.
-         * @param name : handler name.
-         * @param namespace : handler namespace.
+         * Crates a Required Handler.
+         * @param name the handler name.
+         * @param namespace the handler namespace.
          */
         public RequiredHandler(String name, String namespace) {
             m_name = name;
@@ -771,9 +830,10 @@
         }
 
         /**
-         * Equals method. Two handlers are equals if they have same name and namespace or they share the same service reference.
-         * @param object : object to compare to the current object.
-         * @return : true if the two compared object are equals
+         * Equals method.
+         * Two handlers are equals if they have same name and namespace or they share the same service reference.
+         * @param object the object to compare to the current object.
+         * @return <code>true</code> if the two compared object are equals
          * @see java.lang.Object#equals(java.lang.Object)
          */
         public boolean equals(Object object) {
@@ -791,7 +851,8 @@
         }
 
         /**
-         * Gets the factory object used for this handler. The object is get when used for the first time.
+         * Gets the factory object used for this handler. 
+         * The object is get when used for the first time.
          * This method is called with the lock avoiding concurrent modification and on a valid factory.
          * @return the factory object.
          */
@@ -806,7 +867,7 @@
         }
 
         /**
-         * Get the handler full name (namespace:name).
+         * Gets the handler qualified name (<code>namespace:name</code>).
          * @return the handler full name
          */
         public String getFullName() {
@@ -834,7 +895,7 @@
         }
 
         /**
-         * Release the reference of the used factory.
+         * Releases the reference of the used factory.
          * This method is called with the lock on the current factory.
          */
         public void unRef() {
@@ -845,9 +906,9 @@
         }
 
         /**
-         * Set the service reference. If the new service reference is null, it unget the used factory (if already get).
+         * Sets the service reference. If the new service reference is <code>null</code>, it ungets the used factory (if already get).
          * This method is called with the lock on the current factory.
-         * @param ref : new service reference.
+         * @param ref the new service reference.
          */
         public void setReference(ServiceReference ref) {
             m_reference = ref;
@@ -858,10 +919,11 @@
         }
 
         /**
-         * Start level Comparison. This method is used to sort the handler array.
+         * Start level Comparison.
+         * This method is used to sort the handler array.
          * This method is called with the lock.
-         * @param object : object on which compare.
-         * @return -1, 0, +1 according to the comparison of their start level.
+         * @param object the object on which compare.
+         * @return <code>-1</code>, <code>0</code>, <code>+1</code> according to the comparison of their start levels.
          * @see java.lang.Comparable#compareTo(java.lang.Object)
          */
         public int compareTo(Object object) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java
index b4c56e1..aa074ed 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceManager.java
@@ -37,70 +37,78 @@
 import org.osgi.framework.BundleContext;
 
 /**
- * The instance manager class manages one instance of a component type. It manages component lifecycle, component instance creation and handlers.
+ * This class defines the container of primitive instances. It manages content initialization 
+ * and handlers cooperation.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class InstanceManager implements ComponentInstance, InstanceStateListener {
     /**
-     * Name of the component instance.
+     * The name of the component instance.
      */
     protected String m_name;
 
     /**
-     * Name of the component type implementation class.
+     * The name of the component type implementation class.
      */
     protected String m_className;
 
     /**
-     * Handler list.
+     * The handler object list.
      */
     protected final HandlerManager[] m_handlers;
 
     /**
-     * Component state (STOPPED at the beginning).
+     * The current instance state ({@link ComponentInstance#STOPPED} at the beginning).
+     * Possible value are 
+     * <li>{@link ComponentInstance#INVALID}</li>
+     * <li>{@link ComponentInstance#VALID}</li>
+     * <li>{@link ComponentInstance#DISPOSED}</li>
+     * <li>{@link ComponentInstance#STOPPED}</li>
      */
     protected int m_state = STOPPED;
 
     /**
-     * Instance State Listener List.
+     * The instance state listener list.
+     * @see InstanceStateListener
      */
     protected List m_listeners = null;
 
     /**
-     * Parent factory (ComponentFactory).
+     * The instance factory.
      */
     private final ComponentFactory m_factory;
 
     /**
-     * The context of the component.
+     * The bundle context of the instance.
      */
     private final BundleContext m_context;
 
     /**
-     * Map [field, field interceptor list] storing handlers interested by the field.
+     * The map [field, {@link FieldInterceptor} list] storing interceptors monitoring fields.
      * Once configured, this map can't change.
      */
     private Map m_fieldRegistration;
 
     /**
-     * Map [method identifier, method interceptor list] storing handlers interested by the method.
+     * the map [method identifier, {@link MethodInterceptor} list] storing handlers interested by the method.
      * Once configure this map can't change.
      */
     private Map m_methodRegistration;
 
     /**
-     * Manipulated class.
+     * The manipulated class.
      * Once set, this field doesn't change.
      */
     private Class m_clazz;
 
     /**
-     * Instances of the components.
+     * The content of the current instance.
      */
     private List m_pojoObjects;
 
     /**
-     * Factory method. Contains the name of the static method used to create POJO objects.
+     * The factory method used to create content objects.
+     * If <code>null</code>, the regular constructor is used. 
      * Once set, this field is immutable.
      */
     private String m_factoryMethod = null;
@@ -111,25 +119,28 @@
     private boolean m_inTransition = false;
 
     /**
-     * Queue of stored state changed.
+     * The queue of stored state changed.
      */
     private List m_stateQueue = new ArrayList();
 
     /**
-     * Map of [field, value], storing POJO field value.
+     * The map of [field, value], storing POJO managed 
+     * field value.
      */
     private Map m_fields = new HashMap();
 
     /**
-     * Map method [id=>method].
+     * The Map storing the Method objects by ids.
+     * [id=>{@link Method}].
      */
     private Map m_methods = new HashMap();
 
     /**
-     * Construct a new Component Manager.
-     * @param factory : the factory managing the instance manager
-     * @param context : the bundle context to give to the instance
-     * @param handlers : handlers array
+     * Creates a new Component Manager.
+     * The instance is not initialized.
+     * @param factory  the factory managing the instance manager
+     * @param context  the bundle context to give to the instance
+     * @param handlers handler object array
      */
     public InstanceManager(ComponentFactory factory, BundleContext context, HandlerManager[] handlers) {
         m_factory = factory;
@@ -138,10 +149,12 @@
     }
 
     /**
-     * Configure the instance manager. Stop the existing handler, clear the handler list, change the metadata, recreate the handlers
-     * @param metadata : the component type metadata
-     * @param configuration : the configuration of the instance
-     * @throws ConfigurationException : occurs if the metadata are not correct
+     * Configures the instance manager.
+     * Sets the class name, and the instance name as well as the factory method.
+     * Initializes handlers.
+     * @param metadata the component type metadata
+     * @param configuration the configuration of the instance
+     * @throws ConfigurationException if the metadata are not correct
      */
     public void configure(Element metadata, Dictionary configuration) throws ConfigurationException {
         m_className = metadata.getAttribute("classname");
@@ -159,7 +172,7 @@
     }
 
     /**
-     * Get the description of the current instance.
+     * Gets the description of the current instance.
      * @return the instance description.
      * @see org.apache.felix.ipojo.ComponentInstance#getInstanceDescription()
      */
@@ -186,7 +199,7 @@
     }
 
     /**
-     * Get the list of handlers plugged on the instance.
+     * Gets the list of handlers plugged (i.e. attached) on the instance.
      * This method does not need a synchronized block as the handler set is constant.
      * @return the handler array of plugged handlers.
      */
@@ -199,10 +212,11 @@
     }
 
     /**
-     * Return a specified handler.
+     * Returns a specified handler.
+     * This method allows cross-handler interactions.
      * This must does not need a synchronized block as the handler set is constant.
-     * @param name : class name of the handler to find or its qualified name (namespace:name)
-     * @return : the handler, or null if not found
+     * @param name the class name of the handler to find or its qualified name (namespace:name)
+     * @return the handler, or null if not found
      */
     public Handler getHandler(String name) {
         for (int i = 0; i < m_handlers.length; i++) {
@@ -215,11 +229,11 @@
     }
 
     /**
-     * Give access to a field value to the first created pojo.
-     * This method process by analyzing both managed fields and pojo fields (by reflection).
+     * Gives access to a field value of the first created pojo.
+     * This method processes by analyzing both managed fields and pojo fields (by reflection).
      * If no pojo were already created try only on managed fields.
-     * @param fieldName : field name.
-     * @return the field value, null is returned if the value is managed and not already set.
+     * @param fieldName the field name.
+     * @return the field value, <code>null</code> is returned if the value is managed and not already set.
      */
     public synchronized Object getFieldValue(String fieldName) {
         if (m_pojoObjects == null) {
@@ -230,12 +244,12 @@
     }
 
     /**
-     * Give access to a field value to the given created pojo.
-     * This method process by analyzing both managed fields and pojo fields (by reflection).
-     * If the given pojo is null, try only on managed fields.
-     * @param fieldName : field name.
-     * @param pojo : the pojo on which computing field value.
-     * @return the field value, null is returned if the value is managed and not already set.
+     * Gives access to a field value to the given created pojo.
+     * This method processes by analyzing both managed fields and pojo fields (by reflection).
+     * If the given pojo is <code>null</code>, tries only on managed fields.
+     * @param fieldName the field name.
+     * @param pojo  the pojo on which computing field value.
+     * @return the field value, <code>null</code> is returned if the value is managed and not already set.
      */
     public synchronized Object getFieldValue(String fieldName, Object pojo) {
         Object setByContainer = null;
@@ -268,7 +282,9 @@
     }
 
     /**
-     * Start the instance manager.
+     * Starts the instance manager.
+     * This method activates plugged handlers,
+     * and computes the initial instance state.
      */
     public void start() {
         synchronized (this) {
@@ -300,7 +316,10 @@
     }
 
     /**
-     * Stop the instance manager.
+     * Stops the instance manager.
+     * This methods sets the instance state to {@link ComponentInstance#STOPPED},
+     * disables attached handlers, and notifies listeners ({@link InstanceStateListener})
+     * of the instance stopping process.
      */
     public void stop() {
         List listeners = null;
@@ -336,12 +355,17 @@
     }
 
     /**
-     * Dispose the instance.
+     * Disposes the instance.
+     * This method does the following process:
+     * <li>Stop the instance is not {@link ComponentInstance#STOPPED}</li>
+     * <li>Notifies listeners {@link InstanceStateListener} of the destruction</li>
+     * <li>Disposes attached handlers</li>
+     * <li>Clears structures</li>
      * @see org.apache.felix.ipojo.ComponentInstance#dispose()
      */
     public void dispose() {
         List listeners = null;
-        int state = -2;
+        int state = -2; // Temporary state
         synchronized (this) {
             state = m_state; // Stack confinement
             if (m_listeners != null) {
@@ -376,10 +400,11 @@
     }
 
     /**
-     * Set the state of the component instance. if the state changed call the stateChanged(int) method on the handlers. This method has a reentrant
-     * mechanism. If in the flow of the first call the method is called another times, the second call is stored and executed after the first one is
-     * finished.
-     * @param state : the new state
+     * Sets the state of the component instance. 
+     * If the state changes, calls the {@link PrimitiveHandler#stateChanged(int)} method on the attached handlers.
+     * This method has a reentrant mechanism. If in the flow of the first call the method is called another times, 
+     * the second call is stored and executed after the first one finished.
+     * @param state the new state
      */
     public void setState(int state) {
         int originalState = -2;
@@ -443,7 +468,12 @@
     }
 
     /**
-     * Get the actual state of the instance.
+     * Gets the actual state of the instance.
+     * Possible values are:
+     * <li>{@link ComponentInstance#INVALID}</li>
+     * <li>{@link ComponentInstance#VALID}</li>
+     * <li>{@link ComponentInstance#DISPOSED}</li>
+     * <li>{@link ComponentInstance#STOPPED}</li>
      * @return the actual state of the component instance.
      * @see org.apache.felix.ipojo.ComponentInstance#getState()
      */
@@ -452,8 +482,10 @@
     }
 
     /**
-     * Check if the instance if started.
-     * @return true if the instance is started.
+     * Checks if the instance is started.
+     * An instance is started if the state is either 
+     * {@link ComponentInstance#VALID} or {@link ComponentInstance#INVALID}.
+     * @return <code>true</code> if the instance is started.
      * @see org.apache.felix.ipojo.ComponentInstance#isStarted()
      */
     public synchronized boolean isStarted() {
@@ -461,8 +493,8 @@
     }
 
     /**
-     * Register an instance state listener.
-     * @param listener : listener to register.
+     * Registers an instance state listener.
+     * @param listener the listener to register.
      * @see org.apache.felix.ipojo.ComponentInstance#addInstanceStateListener(org.apache.felix.ipojo.InstanceStateListener)
      */
     public synchronized void addInstanceStateListener(InstanceStateListener listener) {
@@ -473,8 +505,8 @@
     }
 
     /**
-     * Unregister an instance state listener.
-     * @param listener : listener to unregister.
+     * Unregisters an instance state listener.
+     * @param listener the listener to unregister.
      * @see org.apache.felix.ipojo.ComponentInstance#removeInstanceStateListener(org.apache.felix.ipojo.InstanceStateListener)
      */
     public synchronized void removeInstanceStateListener(InstanceStateListener listener) {
@@ -487,7 +519,7 @@
     }
 
     /**
-     * Get the factory which create the current instance.
+     * Gets the factory which has created the current instance.
      * @return the factory of the component
      * @see org.apache.felix.ipojo.ComponentInstance#getFactory()
      */
@@ -496,7 +528,7 @@
     }
 
     /**
-     * Load the manipulated class.
+     * Loads the manipulated class.
      */
     private void load() {
         try {
@@ -509,8 +541,8 @@
     }
 
     /**
-     * Get the array of object created by the instance.
-     * @return the created instance of the component instance.
+     * Gets the object array created by the instance.
+     * @return the created content objects of the component instance.
      */
     public synchronized Object[] getPojoObjects() {
         if (m_pojoObjects == null) {
@@ -519,6 +551,17 @@
         return m_pojoObjects.toArray(new Object[m_pojoObjects.size()]);
     }
     
+    /**
+     * Creates a POJO objects.
+     * This method is not synchronized and does require any locks.
+     * If a {@link InstanceManager#m_factoryMethod} is specified,
+     * this method called this static method to creates the object.
+     * Otherwise, the methods uses the regular constructor.
+     * All those methods can receive the {@link BundleContext} in
+     * argument.
+     * @return the created object or <code>null</code> if an error
+     * occurs during the creation.
+     */
     private Object createObject() {
         if (m_clazz == null) {
             load();
@@ -662,13 +705,18 @@
     }
 
     /**
-     * Create an instance of the component. 
-     * This method need to be called one time only for singleton provided service.
-     * @return a new instance
+     * Creates an instance of the content. 
+     * This method needs to be called once only for singleton provided service.
+     * This methods call the {@link InstanceManager#createObject()} method, and adds
+     * the created object to the {@link InstanceManager#m_pojoObjects} list. Then,
+     * it calls the {@link PrimitiveHandler#onCreation(Object)} methods on attached 
+     * handlers.
+     * @return a new instance or <code>null</code> if an error occurs during the
+     * creation.
      */
     public Object createPojoObject() {
         Object instance = createObject();
-
+        
         // Add the new instance in the instance list.
         synchronized (this) {
             if (m_pojoObjects == null) {
@@ -678,6 +726,7 @@
         }
         // Call createInstance on Handlers :
         for (int i = 0; i < m_handlers.length; i++) {
+            // This methods must be call without the monitor lock.
             ((PrimitiveHandler) m_handlers[i].getHandler()).onCreation(instance);
         }
         
@@ -685,8 +734,20 @@
     }
 
     /**
-     * Get the first object created by the instance. If no object created, create and return one object.
-     * @return the instance of the component instance to use for singleton component
+     * Gets the first object created by the instance. 
+     * If no object created, creates and returns a POJO object.
+     * This methods call the {@link InstanceManager#createObject()} method, and adds
+     * the created object to the {@link InstanceManager#m_pojoObjects} list. Then,
+     * it calls the {@link PrimitiveHandler#onCreation(Object)} methods on attached 
+     * handlers.
+     * <br/>
+     * <p>
+     * <b>TODO</b> this method has a potential race condition if two threads require a pojo
+     * object at the same time. Only one object will be created, but the second thread
+     * can receive the created object before the {@link PrimitiveHandler#onCreation(Object)}
+     * calls.
+     * </p>
+     * @return the pojo object of the component instance to use for singleton component
      */
     public Object getPojoObject() {
         Object pojo = null;
@@ -714,7 +775,7 @@
     }
 
     /**
-     * Get the manipulated class.
+     * Gets the manipulated class.
      * The method does not need to be synchronized.
      * Reassigning the internal class will use the same class object.
      * @return the manipulated class
@@ -727,11 +788,14 @@
     }
 
     /**
-     * Register an handler. The handler will be notified of event on each field given in the list.
-     * @param handler : the handler to register
-     * @param fields : the field metadata list
-     * @param methods : the method metadata list
-     * @deprecated use register(FieldMetadata fm, FieldInterceptor fi) and register(MethodMetadata mm, MethodInterceptor mi) instead. 
+     * Registers an handler.
+     * This methods is called by handler wanting to monitor
+     * fields and/or methods of the implementation class.  
+     * @param handler the handler to register
+     * @param fields the field metadata list
+     * @param methods the method metadata list
+     * @deprecated use {@link InstanceManager#register(FieldMetadata, FieldInterceptor)}
+     * and {@link InstanceManager#register(FieldMetadata, MethodInterceptor)} instead. 
      */
     public void register(PrimitiveHandler handler, FieldMetadata[] fields, MethodMetadata[] methods) {
         for (int i = 0; fields != null && i < fields.length; i++) {
@@ -744,9 +808,11 @@
     }
     
     /**
-     * Register a field interceptor.
-     * @param field : intercepted field
-     * @param interceptor : interceptor
+     * Registers a field interceptor.
+     * A field interceptor will be notified of field access of the
+     * implementation class. Note that handlers are field interceptors.
+     * @param field the field to monitor
+     * @param interceptor the field interceptor object
      */
     public void register(FieldMetadata field, FieldInterceptor interceptor) {
         if (m_fieldRegistration == null) {
@@ -771,9 +837,11 @@
     }
     
     /**
-     * Register a method interceptor.
-     * @param method : intercepted method
-     * @param interceptor : interceptor
+     * Registers a method interceptor.
+     * A method interceptor will be notified of method entries, exits
+     * and errors. Note that handlers are method interceptors.
+     * @param method the field to monitor
+     * @param interceptor the field interceptor object
      */
     public void register(MethodMetadata method, MethodInterceptor interceptor) {
         if (m_methodRegistration == null) {
@@ -798,11 +866,14 @@
     }
 
     /**
-     * This method is called by the manipulated class each time that a GETFIELD instruction is found. The method ask to each handler which value need
-     * to be returned.
-     * @param pojo : the pojo object on which the field was get
-     * @param fieldName : the field name on which the GETFIELD instruction is called
-     * @return the value decided by the last asked handler (throw a warning if two fields decide two different values)
+     * This method is called by the manipulated class each time that a GETFIELD instruction is executed.
+     * The method asks to each attached handler monitoring this field which value need
+     * to be injected (i.e. returned) by invoking the {@link PrimitiveHandler#onGet(Object, String, Object)}
+     * method. If the field value changes, this method call the {@link PrimitiveHandler#onSet(Object, String, Object)}
+     * method on each field interceptor monitoring the field in order to advertize the new value.
+     * @param pojo the pojo object on which the field was get
+     * @param fieldName the field name on which the GETFIELD instruction is called
+     * @return the value decided by the last asked handler (throws a warning if two fields decide two different values)
      */
     public Object  onGet(Object pojo, String fieldName) {
         Object initialValue = null;
@@ -850,10 +921,12 @@
     }
 
     /**
-     * Dispatch entry method event on registered handler.
-     * @param pojo : the pojo object on which method is invoked.
-     * @param methodId : method id
-     * @param args : argument array
+     * Dispatches entry method events on registered method interceptors.
+     * This method calls the {@link PrimitiveHandler#onEntry(Object, Method, Object[])}
+     * methods on method interceptors monitoring the method.
+     * @param pojo the pojo object on which method is invoked.
+     * @param methodId the method id used to compute the {@link Method} object.
+     * @param args the argument array
      */
     public void onEntry(Object pojo, String methodId, Object[] args) {
         if (m_methodRegistration == null) { // Immutable field.
@@ -867,11 +940,15 @@
     }
 
     /**
-     * Dispatch exit method event on registered handler. The given returned object is an instance of Exception if the method has launched an
-     * exception. If the given object is null, either the method returns void, either the method has returned null.
-     * @param pojo : the pojo object on which the method was invoked
-     * @param methodId : method id
-     * @param result : returned object.
+     * Dispatches exit method events on registered method interceptors.
+     * The given returned object is an instance of {@link Exception} if the method thrown an
+     * exception. If the given object is <code>null</code>, either the method returns <code>void</code>,
+     * or the method has returned <code>null</code>
+     * This method calls the {@link PrimitiveHandler#onExit(Object, Method, Object[])} and the 
+     * {@link PrimitiveHandler#onFinally(Object, Method)} methods on method interceptors monitoring the method.
+     * @param pojo the pojo object on which method was invoked.
+     * @param methodId the method id used to compute the {@link Method} object.
+     * @param result the returned object.
      */
     public void onExit(Object pojo, String methodId, Object result) {
         if (m_methodRegistration == null) {
@@ -888,11 +965,14 @@
     }
 
     /**
-     * Dispatch error method event on registered handler. The given returned object is an instance of Exception if the method has thrown an exception.
-     * If the given object is null, either the method returns void, either the method has returned null.
-     * @param pojo : the pojo object on which the method was invoked
-     * @param methodId : method id
-     * @param error : throwable object.
+     * Dispatches error method events on registered method interceptors.
+     * or the method has returned <code>null</code>
+     * This method calls the {@link PrimitiveHandler#onExit(Object, Method, Object[])} and the 
+     * {@link PrimitiveHandler#onFinally(Object, Method)} methods on method interceptors monitoring 
+     * the method.
+     * @param pojo the pojo object on which the method was invoked
+     * @param methodId the method id used to compute the {@link Method} object.
+     * @param error the Throwable object.
      */
     public void onError(Object pojo, String methodId, Throwable error) {        
         if (m_methodRegistration == null) {
@@ -909,9 +989,11 @@
     }
 
     /**
-     * Get method object by id.
-     * @param methodId : method id
-     * @return : the method object or null if the method cannot be found.
+     * Computes the {@link Method} object from the given id.
+     * Once computes, a map is used as a cache to avoid to recompute for
+     * the same id.
+     * @param methodId the method id
+     * @return the method object or <code>null</code> if the method cannot be found.
      */
     private Method getMethodById(String methodId) {
         // Not necessary synchronized as recomputing the methodID will give the same Method twice.
@@ -940,10 +1022,14 @@
     }
 
     /**
-     * This method is called by the manipulated class each time that a PUTFILED instruction is found. the method send to each handler the new value.
-     * @param pojo : the pojo object on which the field was set
-     * @param fieldName : the field name on which the PUTFIELD instruction is called
-     * @param objectValue : the value of the field
+     * This method is called by the manipulated class each time that a PUTFILED instruction is executed. 
+     * The method calls the {@link PrimitiveHandler#onSet(Object, String, Object)} method on each field
+     * interceptors monitoring this field.
+     * This method can be invoked with a <code>null</code> pojo argument when the changes comes from another
+     * handler.
+     * @param pojo the pojo object on which the field was set
+     * @param fieldName the field name on which the PUTFIELD instruction is called
+     * @param objectValue the new value of the field
      */
     public void onSet(Object pojo, String fieldName, Object objectValue) {
         Object value = null; // Stack confinement
@@ -961,8 +1047,9 @@
         }
     }
 
+    
     /**
-     * Get the bundle context used by this component instance.
+     * Gets the bundle context used by this component instance.
      * @return the context of the component.
      * @see org.apache.felix.ipojo.ComponentInstance#getContext()
      */
@@ -970,16 +1057,31 @@
         return m_context; // Immutable
     }
 
+    /**
+     * Gets the global bundle context. This is the bundle context
+     * of the bundle declaring the component type.
+     * @return the bundle context of the bundle declaring the component
+     * type.
+     */
     public BundleContext getGlobalContext() {
         return ((IPojoContext) m_context).getGlobalContext(); // Immutable
     }
-
+    
+    
+    /**
+     * Gets the local service context. This service context gives
+     * access to the 'local' service registry (the composite one).
+     * If the instance lives in the global (i.e. OSGi) context,
+     * this method returns <code>null</code>
+     * @return the local service context or <code>null</code> if the
+     * instance doesn't live in a composite.
+     */
     public ServiceContext getLocalServiceContext() {
         return ((IPojoContext) m_context).getServiceContext(); // Immutable
     }
 
     /**
-     * Get the instance name.
+     * Gets the instance name.
      * @return the instance name.
      * @see org.apache.felix.ipojo.ComponentInstance#getInstanceName()
      */
@@ -988,8 +1090,15 @@
     }
 
     /**
-     * Reconfigure the current instance.
-     * @param configuration : the new configuration to push
+     * Reconfigures the current instance.
+     * Reconfiguring an instance means re-injecting a new
+     * instance configuration. Some properties are immutable
+     * such as the instance name.
+     * This methods calls the {@link PrimitiveHandler#reconfigure(Dictionary)}
+     * methods on each attached handler, and then recompute the instance
+     * state. Note that the reconfiguration process does not deactivate the 
+     * instance. 
+     * @param configuration the new configuration to push
      * @see org.apache.felix.ipojo.ComponentInstance#reconfigure(java.util.Dictionary)
      */
     public void reconfigure(Dictionary configuration) {
@@ -1011,19 +1120,22 @@
     }
 
     /**
-     * Get the implementation class of the component type.
+     * Gets the implementation class of the component type.
      * This method does not need to be synchronized as the
      * class name is constant once set. 
-     * @return the class name of the component type.
+     * @return the class name of the component implementation.
      */
     public String getClassName() {
         return m_className;
     }
 
     /**
-     * State Change listener callback. This method is notified at each time a plugged handler becomes invalid.
-     * @param instance : changing instance
-     * @param newState : new state
+     * State Change listener callback.
+     * This method is called every time that a plugged handler becomes valid or invalid.
+     * This method computes the new instance state and applies it (by calling the
+     * {@link InstanceManager#setState(int)} method.
+     * @param instance the handler becoming valid or invalid
+     * @param newState the new state of the handler
      * @see org.apache.felix.ipojo.InstanceStateListener#stateChanged(org.apache.felix.ipojo.ComponentInstance, int)
      */
     public void stateChanged(ComponentInstance instance, int newState) {
@@ -1055,7 +1167,9 @@
     }
 
     /**
-     * Get the list of registered fields. This method is invoked by the POJO itself.
+     * Gets the list of registered fields (containing field names). 
+     * This method is invoked by the POJO itself during
+     * its initialization.
      * @return the set of registered fields.
      */
     public Set getRegistredFields() {
@@ -1066,7 +1180,9 @@
     }
 
     /**
-     * Get the list of registered methods. This method is invoked by the POJO itself.
+     * Gets the list of registered methods (containing method ids). 
+     * This method is invoked by the POJO itself during its
+     * initialization.
      * @return the set of registered methods.
      */
     public Set getRegistredMethods() {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java
index 5d63fc1..d6ec53a 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/InstanceStateListener.java
@@ -19,17 +19,25 @@
 package org.apache.felix.ipojo;
 
 /**
- * Instance state listener.
- * This listener allows anyone to be notified when the listened instance state changes. 
+ * This class defines instance state listeners.
+ * An instance state listener is notified of instance state changes. It needs to be
+ * registered on the instance by invoking the ({@link ComponentInstance#addInstanceStateListener(InstanceStateListener)}
+ * method. Once registered, the listener can track instance state changes. 
+ * Received states are:
+ * <li>{@link ComponentInstance#VALID}</li>
+ * <li>{@link ComponentInstance#INVALID}</li>
+ * <li>{@link ComponentInstance#STOPPED}</li>
+ * <li>{@link ComponentInstance#DISPOSED}</li> 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface InstanceStateListener {
     
     /**
-     * State change listener.
-     * Each time an instance state change, this method is called.
-     * @param instance : changing instance
-     * @param newState : new instance state
+     * State change listener callback method.
+     * Every time that a monitored instance's state changes,
+     * this method is called with the instance and the new state.
+     * @param instance the changing instance
+     * @param newState the new instance state
      */
     void stateChanged(ComponentInstance instance, int newState);
 }
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java
index 951452f..854405f 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/MethodInterceptor.java
@@ -22,47 +22,52 @@
 
 /**
 * Method interceptor.
-* A class implementing this interface is able to be notified of method invocation.
-* The listener need to be register on the instance manager. 
-* For event are send to the listener : before the method entry, after the method returns, 
-* when an error is thrown by the method, and before the after either a returns or an error (finally) 
-* 
+* A class implementing this interface is able to be notified of method invocations (
+* i.e. entries, exits, and errors).
+* The listener needs to be register on the instance manager with the 
+* {@link InstanceManager#register(org.apache.felix.ipojo.parser.MethodMetadata, MethodInterceptor)}
+* method. 
+* Events are sent before the method entry (onEntry), after the method returns (onExit), 
+* when an error is thrown by the method (onError), and before the after either a returns or an error (onFinally)
 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */
 public interface MethodInterceptor {
     
     /**
-     * This method is called when the execution enter in a method.
-     * @param pojo : pojo on which the method is called.
-     * @param method : method invoked.
-     * @param args arguments array.
+     * This method is called when the execution enters in a method.
+     * @param pojo the pojo on which the method is called.
+     * @param method the invoked method.
+     * @param args the arguments array.
      */
     void onEntry(Object pojo, Method method, Object[] args);
 
     /**
-     * This method is called when the execution exit a method (before a return or a throw).
-     * If the given returned object is null, either the method is void, either it returns null.
+     * This method is called when the execution exits a method :
+     * before a <code>return</code>.
+     * If the given returned object is <code>null</code>, either the method is 
+     * <code>void</code>, or it returns <code>null</code>.
      * You must not modified the returned object.
-     * @param pojo : the pojo on which the method exits.
-     * @param method : exiting method.
-     * @param returnedObj : the returned object (boxed for primitive type)
+     * @param pojo the pojo on which the method exits.
+     * @param method the exiting method.
+     * @param returnedObj the the returned object (boxed for primitive type)
      */
     void onExit(Object pojo, Method method, Object returnedObj);
     
     /**
-     * This method is called when the execution throw an exception in the given method.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
-     * @param throwable : the thrown exception
+     * This method is called when the execution throws an exception in the given 
+     * method.
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
+     * @param throwable the thrown exception
      */
     void onError(Object pojo, Method method, Throwable throwable);
     
     /**
-     * This method is called when the execution of a method will terminate : 
+     * This method is called when the execution of a method is going to terminate : 
      * just before to throw an exception or before to return.
-     * OnError or OnExit was already called.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
+     * (onError or onExit was already called).
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
      */
     void onFinally(Object pojo, Method method);
 
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java
index 3ba91b4..9bc4efb 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/MissingHandlerException.java
@@ -22,7 +22,9 @@
 
 /**
  * Missing Handler Exception.
- * This exception occurs when an handler is missing to build an instance.
+ * This exception occurs when an handler factory is missing to create an instance.
+ * In fact, when a required handler factory is not avialable or valid, the {@link Handler}
+ * object cannot be created, and so the instance container cannot be completed.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class MissingHandlerException extends Exception {
@@ -33,13 +35,15 @@
     private static final long serialVersionUID = 5047792897590881478L;
     
     /**
-     * Message. 
+     * The message. 
      */
     private String m_message;
     
     /**
-     * Constructor.
-     * @param missing : list of missing handlers.
+     * Creates a MissingHandlerException.
+     * This methods computes the message from
+     * the given list.
+     * @param missing the list of missing handlers.
      */
     public MissingHandlerException(List missing) {
         super();
@@ -50,8 +54,8 @@
     }
     
     /**
-     * Get the error message.
-     * @return : the error message
+     * Gets the error message.
+     * @return the error message
      * @see java.lang.Throwable#getMessage()
      */
     public String getMessage() {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java
index 797d02e..075f4c7 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/Nullable.java
@@ -20,7 +20,12 @@
 
 /**
  * A Nullable object must implement this interface.
- * 
+ * This allows to the code checking if the injected object is
+ * a Nullable object or not such as in:<br/>
+ * <code>if(foo instanceof Nullable){...}</code>
+ * <br/>
+ * This interface does not define any methods. Nullable objects owns
+ * the same methods than the 'real' object.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface Nullable {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java
index d51fa18..8bc7779 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/Pojo.java
@@ -19,16 +19,16 @@
 package org.apache.felix.ipojo;
 
 /**
- * Interface implemented by each object created through an manipulated class.
- * This interface allow to get the component instance from the object.
+ * Interface implemented by each manipulated class. 
+ * This interface allows getting the component instance from the object.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface Pojo {
 
     /**
-     * Get the instance container which create the current object.
-     * @return the component instance who create this object.
+     * Gets the instance container which creates the current object.
+     * @return the component instance which creates this object.
      */
     ComponentInstance getComponentInstance();
 
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java
index 501050c..28ef113 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/PolicyServiceContext.java
@@ -34,52 +34,65 @@
 import org.osgi.framework.ServiceRegistration;
 
 /**
- * The policy service context is a service context aiming to solve service requirement.
- * It's parameterized by a resolving policy. Three policies are managed : 
- * - Local : services are only solve un the local service registry
- * - Global : services are resolved only in the global (i.e. OSGi) service registry
- * - Local and Global : services are resolved inside the local registry and the global registry  
+ * The policy service context is a service context aiming to resolve service dependencies
+ * inside different service context according to a policy.
+ * So, the policy service context behavior follows one of the three following policy:
+ * <li> Local : services are only resolved in the local service context.</li>
+ * <li> Global : services are only resolved in the global context (hte OSGi one)</li>
+ * <li> Local and Global : services are resolved inside the local context and inside
+ * the global context</li>
+ *    
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class PolicyServiceContext implements ServiceContext {
     
     /**
-     * Resolving policy, look only in the composite.
+     * Resolving policy, resolves services only in the composite
+     * context (local).
+     * This policy is the default one for services inherited from
+     * service-level dependencies.
      */
     public static final int LOCAL = 0;
     
     /**
-     * Resolving policy, look inside the composite and in the global scope.
+     * Resolving policy, resolves services only in the composite
+     * (local) and in the global context.
      * This policy is the default one for implementation dependency.
      */
     public static final int LOCAL_AND_GLOBAL = 1;
     
     /**
-     * Resolving policy, look inside the global only.
+     * Resolving policy, resolves services inside the global context
+     * only.
      */
     public static final int GLOBAL = 2;
     
     /**
-     * Global service registry.
+     * The global service registry.
+     * Targets the OSGi service registry.
      */
     public BundleContext m_global;
     
     /**
-     * Local (Composite) Service Registry.
+     * The local (Composite) Service Registry.
      */
     public ServiceContext m_local;
     
     /**
-     * Resolving policy.
+     * The resolving policy to use to resolve
+     * dependencies.
      */
     private int m_policy = LOCAL_AND_GLOBAL;
     
     
     /**
-     * Create a new PolicyServiceContext.
-     * @param global : global bundle context
-     * @param local : parent (local) service context
-     * @param policy : resolution policy
+     * Creates a PolicyServiceContext.
+     * If the local context is null, sets the policy to
+     * {@link PolicyServiceContext#GLOBAL}, else use the 
+     * given policy.
+     * @param global the global bundle context
+     * @param local the parent (local) service context
+     * @param policy the resolution policy
      */
     public PolicyServiceContext(BundleContext global, ServiceContext local, int policy) {
         m_global = global;
@@ -92,10 +105,12 @@
     }
 
     /**
-     * Add a service listener according to the policy.
-     * @param listener : the listener to add
-     * @param filter : LDAP filter
-     * @throws InvalidSyntaxException occurs when the filter is malformed.
+     * Adds a service listener according to the policy.
+     * Be aware, that the listener can be registered both in the local and in the global context
+     * if the {@link PolicyServiceContext#LOCAL_AND_GLOBAL} is used.
+     * @param listener the listener to add
+     * @param filter the LDAP filter
+     * @throws InvalidSyntaxException if the filter is malformed.
      * @see org.apache.felix.ipojo.ServiceContext#addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)
      */
     public void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException {
@@ -109,8 +124,10 @@
     }
 
     /**
-     * Add a service listener according to the policy.
-     * @param listener : the listener to add
+     * Adds a service listener according to the policy.
+     * Be aware, that the listener can be registered both in the local and in the global context
+     * if the {@link PolicyServiceContext#LOCAL_AND_GLOBAL} is used.
+     * @param listener the listener to add
      * @see org.apache.felix.ipojo.ServiceContext#addServiceListener(org.osgi.framework.ServiceListener)
      */
     public void addServiceListener(ServiceListener listener) {
@@ -123,11 +140,13 @@
     }
 
     /**
-     * Get all service references. These reference are found inside the local registry, global registry or both according to the policy.
-     * @param clazz : required service specification.
-     * @param filter : LDAP filter
-     * @return the array of service reference, null if no service available
-     * @throws InvalidSyntaxException occurs when the LDAP filter is malformed 
+     * Gets all service references.
+     * These references are found inside the local registry, global registry or both according to the policy.
+     * The returned array can contain service references from both context.
+     * @param clazz the required service specification.
+     * @param filter the LDAP filter
+     * @return the array of service reference, <code>null</code> if no service available
+     * @throws InvalidSyntaxException if the LDAP filter is malformed 
      * @see org.apache.felix.ipojo.ServiceContext#getAllServiceReferences(java.lang.String, java.lang.String)
      */
     public ServiceReference[] getAllServiceReferences(String clazz,
@@ -147,8 +166,9 @@
     }
 
     /**
-     * Get the service object for the given reference.
-     * @param ref : the service reference
+     * Gets the service object for the given references.
+     * The service is get inside the context according to the policy.
+     * @param ref the service reference
      * @return the service object
      * @see org.apache.felix.ipojo.ServiceContext#getService(org.osgi.framework.ServiceReference)
      */
@@ -172,9 +192,10 @@
     }
 
     /**
-     * Get a service reference for the required service specification.
-     * @param clazz : the required service specification
-     * @return a service reference or null if not consistent service available
+     * Gets a service reference for the required service specification.
+     * The service is looked inside the context according to the policy.
+     * @param clazz the required service specification
+     * @return a service reference or <code>null</code> if no matching service available
      * @see org.apache.felix.ipojo.ServiceContext#getServiceReference(java.lang.String)
      */
     public ServiceReference getServiceReference(String clazz) {
@@ -197,10 +218,11 @@
 
     /**
      * Get a service reference for the required service specification.
-     * @param clazz : the required service specification
-     * @param filter : LDAP filter
-     * @return a service reference array or null if not consistent service available
-     * @throws InvalidSyntaxException occurs when the LDAP filter is malformed 
+     * The services are looked inside the context according to the policy.
+     * @param clazz the required service specification
+     * @param filter the LDAP filter
+     * @return a service reference array or <code>null</code> if not consistent service available
+     * @throws InvalidSyntaxException if the LDAP filter is malformed 
      * @see org.apache.felix.ipojo.ServiceContext#getServiceReference(java.lang.String)
      */
     public ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException {
@@ -220,10 +242,11 @@
     }
     
     /**
-     * Compute the service reference array from the two given set of service references.
-     * @param refLocal : local references
-     * @param refGlobal : global references
-     * @return the set of service reference
+     * Computes the service reference array from the two given set of service references
+     * according to the policy.
+     * @param refLocal the set of local references
+     * @param refGlobal the set of global references
+     * @return the set of service references
      */
     private ServiceReference[] computeServiceReferencesFromBoth(ServiceReference[] refLocal, ServiceReference[] refGlobal) {
         if (refLocal == null) {
@@ -240,31 +263,33 @@
 
     /**
      * This method is not supported.
-     * @param clazzes : specifications
-     * @param service : service object
-     * @param properties : service properties
-     * @return : the service registration object
+     * This context can only be used to resolve service dependencies.
+     * @param clazzes the specifications
+     * @param service the service object
+     * @param properties the service properties
+     * @return the service registration object
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
      */
     public ServiceRegistration registerService(String[] clazzes, Object service, Dictionary properties) {
-        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not service providing");
+        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not to provide services");
     }
 
     /**
      * This method is not supported.
-     * @param clazz : specification
-     * @param service : service object
-     * @param properties : service properties
-     * @return : the service registration object
+     * This context can only be used to resolve service dependencies.
+     * @param clazz the specification
+     * @param service the service object
+     * @param properties the service properties to publish
+     * @return the service registration object
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String, java.lang.Object, java.util.Dictionary)
      */
     public ServiceRegistration registerService(String clazz, Object service, Dictionary properties) {
-        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not service providing");
+        throw new UnsupportedOperationException("PolicyServiceContext can only be used for service dependency and not to provide services");
     }
 
     /**
-     * Remove a service listener.
-     * @param listener : the service listener to remove
+     * Removes a service listener.
+     * @param listener the service listener to remove
      * @see org.apache.felix.ipojo.ServiceContext#removeServiceListener(org.osgi.framework.ServiceListener)
      */
     public void removeServiceListener(ServiceListener listener) {
@@ -277,9 +302,9 @@
     }
 
     /**
-     * Unget the service reference.
-     * @param reference : the service reference to unget.
-     * @return true if the unget is successful.
+     * Ungets the service reference.
+     * @param reference the service reference to unget.
+     * @return <code>true</code> if the service release if the reference is no more used.
      * @see org.apache.felix.ipojo.ServiceContext#ungetService(org.osgi.framework.ServiceReference)
      */
     public boolean ungetService(ServiceReference reference) {
@@ -291,7 +316,7 @@
     }
 
     /**
-     * Add a bundle listener.
+     * Adds a bundle listener.
      * Delegate on the global bundle context.
      * @param arg0 : bundle listener to add
      * @see org.osgi.framework.BundleContext#addBundleListener(org.osgi.framework.BundleListener)
@@ -301,8 +326,8 @@
     }
 
     /**
-     * Add a framework listener.
-     * Delegate on the global bundle context.
+     * Adds a framework listener.
+     * Delegates on the global bundle context.
      * @param arg0 : framework listener to add.
      * @see org.osgi.framework.BundleContext#addFrameworkListener(org.osgi.framework.FrameworkListener)
      */
@@ -311,10 +336,10 @@
     }
 
     /**
-     * Create a LDAP filter.
-     * @param arg0 : String-form of the filter
+     * Creates a LDAP filter.
+     * @param arg0 the String-form of the filter
      * @return the created filter object
-     * @throws InvalidSyntaxException : if the given argument is not a valid against the LDAP grammar.
+     * @throws InvalidSyntaxException if the given argument is not a valid against the LDAP grammar.
      * @see org.osgi.framework.BundleContext#createFilter(java.lang.String)
      */
     public Filter createFilter(String arg0) throws InvalidSyntaxException {
@@ -322,7 +347,7 @@
     }
 
     /**
-     * Get the current bundle.
+     * Gets the current bundle.
      * @return the current bundle
      * @see org.osgi.framework.BundleContext#getBundle()
      */
@@ -331,8 +356,8 @@
     }
 
     /**
-     * Get the bundle object with the given id.
-     * @param bundleId : bundle id
+     * Gets the bundle object with the given id.
+     * @param bundleId the bundle id
      * @return the bundle object
      * @see org.osgi.framework.BundleContext#getBundle(long)
      */
@@ -341,7 +366,7 @@
     }
 
     /**
-     * Get installed bundles.
+     * Gets installed bundles.
      * @return the list of installed bundles
      * @see org.osgi.framework.BundleContext#getBundles()
      */
@@ -351,8 +376,8 @@
 
 
     /**
-     * Get a data file.
-     * @param filename : File name.
+     * Gets a data file.
+     * @param filename the File name.
      * @return the File object
      * @see org.osgi.framework.BundleContext#getDataFile(java.lang.String)
      */
@@ -361,9 +386,10 @@
     }
 
     /**
-     * Get a property value.
-     * @param key : key of the asked property
-     * @return the property value (object) or null if no property are associated with the given key
+     * Gets a property value.
+     * @param key the key of the asked property
+     * @return the property value (object) or <code>null</code> if no property
+     * are associated with the given key
      * @see org.osgi.framework.BundleContext#getProperty(java.lang.String)
      */
     public String getProperty(String key) {
@@ -371,10 +397,10 @@
     }
 
     /**
-     * Install a bundle.
-     * @param location : URL of the bundle to install
+     * Installs a bundle.
+     * @param location the URL of the bundle to install
      * @return the installed bundle
-     * @throws BundleException : if the bundle cannot be installed correctly
+     * @throws BundleException if the bundle cannot be installed correctly
      * @see org.osgi.framework.BundleContext#installBundle(java.lang.String)
      */
     public Bundle installBundle(String location) throws BundleException {
@@ -382,11 +408,11 @@
     }
 
     /**
-     * Install a bundle.
-     * @param location : URL of the bundle to install
-     * @param input : 
+     * Installs a bundle.
+     * @param location the URL of the bundle to install
+     * @param input the input stream to load the bundle content
      * @return the installed bundle
-     * @throws BundleException : if the bundle cannot be installed correctly
+     * @throws BundleException if the bundle cannot be installed correctly
      * @see org.osgi.framework.BundleContext#installBundle(java.lang.String, java.io.InputStream)
      */
     public Bundle installBundle(String location, InputStream input) throws BundleException {
@@ -394,8 +420,8 @@
     }
 
     /**
-     * Remove a bundle listener.
-     * @param listener : the listener to remove
+     * Removes the bundle listener.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeBundleListener(org.osgi.framework.BundleListener)
      */
     public void removeBundleListener(BundleListener listener) {
@@ -403,8 +429,8 @@
     }
 
     /**
-     * Remove a framework listener.
-     * @param listener : the listener to remove
+     * Removes a framework listener.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeFrameworkListener(org.osgi.framework.FrameworkListener)
      */
     public void removeFrameworkListener(FrameworkListener listener) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java
index 2016dae..7e15c11 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/PrimitiveHandler.java
@@ -20,148 +20,195 @@
 
 import java.lang.reflect.Method;
 
-import org.apache.felix.ipojo.metadata.Element;
 import org.apache.felix.ipojo.parser.PojoMetadata;
 import org.apache.felix.ipojo.util.Logger;
 
 
-
 /**
-* Abstract class to extends for primitive handler.
-* 
+* This class defines common mechanisms of primitive handlers.
+* Primitive handlers are handler composing the container of primitive
+* component instances (declared by the 'component' element inside the
+* iPOJO descriptor).
+* Note that this class also defines default method implementation.
+* Classes overriding this class can change the behavior of those methods.
 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */
 public abstract class PrimitiveHandler extends Handler implements FieldInterceptor, MethodInterceptor {
     
     /**
-     * "Primitive" Handler type (value).
+     * The "Primitive" Handler type (value).
      */
     public static final String HANDLER_TYPE = "primitive";
     
     /**
-     * Reference on the instance manager.
+     * The reference on the instance manager.
      */
     private InstanceManager m_manager;
     
     
     /**
-     * Factory of the instance manager. 
+     * The factory of the instance manager. 
      */
     private ComponentFactory m_factory;
     
     /**
-     * Attach the current handler to the given instance.
-     * @param manager ! the instance on which the current handler will be attached.
+     * Attaches the current handler to the given instance.
+     * @param manager the instance on which the current handler will be attached.
      * @see org.apache.felix.ipojo.Handler#attach(org.apache.felix.ipojo.ComponentInstance)
      */
     protected final void attach(ComponentInstance manager) {
         m_manager = (InstanceManager) manager;
     }
     
+    /**
+     * Sets the factory of the managed instance.
+     * @param factory the factory 
+     * @see org.apache.felix.ipojo.Handler#setFactory(org.apache.felix.ipojo.Factory)
+     */
     public final void setFactory(Factory factory) {
         m_factory = (ComponentFactory) factory;
     }
     
+    /**
+     * gets the logger of the managed instance.
+     * @return the logger to use to log messages.
+     * @see org.apache.felix.ipojo.Handler#getLogger()
+     */
     public Logger getLogger() {
         return m_factory.getLogger();
     }
     
+    /**
+     * Gets the instance manager managing the instance.
+     * @return the instance manager
+     */
     public InstanceManager getInstanceManager() {
         return m_manager;
     }
     
+    /**
+     * Gets the factory which creates the managed instance.
+     * @return the factory which creates the managed instance.
+     */
     public ComponentFactory getFactory() {
         return m_factory;
     }
     
-    public Element[] getMetadata() {
-        return null;
-    }
-    
+    /**
+     * Gets the PojoMetadata of the content of the managed
+     * instance. This method allows getting manipulation
+     * metadata.
+     * @return the information about the content of the
+     * managed instance.
+     */
     public PojoMetadata getPojoMetadata() {
         return m_factory.getPojoMetadata();
     }
     
     /**
-     * Get a plugged handler of the same container.
-     * This method must be call only in the start method (or after). 
-     * In the configure method, this method can not return a consistent
-     * result as all handlers are not plugged. 
-     * @param name : name of the handler to find (class name or qualified handler name (ns:name)). 
-     * @return the handler object or null if the handler is not found.
+     * Gets a plugged handler of the same container.
+     * This method must be called only in the start method (or after). 
+     * In the configure method, this method can be inconsistent
+     * as all handlers are not initialized. 
+     * @param name the name of the handler to find (class name or qualified
+     * handler name (<code>ns:name</code>)). 
+     * @return the handler object or <code>null</code> if the handler is not found.
      */
     public final Handler getHandler(String name) {
         return m_manager.getHandler(name);
     }
     
     /**
-     * This method is called when a PUTFIELD operation is detected.
-     * @param pojo : the pojo object setting the value
-     * @param fieldName : the field name
-     * @param value : the value passed to the field
+     * Callback method called when a managed field 
+     * receives a new value. The given pojo can be
+     * null if the new value is set by another handler.
+     * This default implementation does nothing. 
+     * @param pojo the pojo object setting the value
+     * @param fieldName the field name
+     * @param value the value received by the field
+     * @see FieldInterceptor#onSet(Object, String, Object)
      */
     public void onSet(Object pojo, String fieldName, Object value) {
         // Nothing to do in the default implementation
     }
 
     /**
-     * This method is called when a GETFIELD operation is detected.
-     * @param pojo : the pojo object getting the value
-     * @param fieldName : the field name
-     * @param value : the value passed to the field (by the previous call)
-     * @return : the managed value of the field
+     * Callback method called when a managed field
+     * asks for a value.
+     * The default implementation returned the previously
+     * injected value.
+     * @param pojo the pojo object requiring the value
+     * @param fieldName the field name
+     * @param value the value passed to the field (by the previous call)
+     * @return the value to inject, of the previous value if the handler
+     * don't want to inject a value.
+     * @see FieldInterceptor#onGet(Object, String, Object)
      */
     public Object onGet(Object pojo, String fieldName, Object value) {
         return value;
     }
     
     /**
-     * This method is called when the execution enter in a method.
-     * @param pojo : pojo on which the method is called.
-     * @param method : method invoked.
-     * @param args arguments array.
+     * Callback method called when a method will be invoked.
+     * This default implementation does nothing. 
+     * @param pojo the pojo on which the method is called.
+     * @param method the method invoked.
+     * @param args the arguments array.
+     * @see MethodInterceptor#onEntry(Object, Method, Object[])
      */
     public void onEntry(Object pojo, Method method, Object[] args) { 
         // Nothing to do in the default implementation
     }
 
     /**
-     * This method is called when the execution exit a method (before a return or a throw).
-     * If the given returned object is null, either the method is void, either it returns null.
+     * Callback method called when a method ends.
+     * This method is called when a thread exits a method (before a return or a throw).
+     * If the given returned object is <code>null</code>, either the method is 
+     * <code>void</code>, or it returns <code>null</code>.
      * You must not modified the returned object.
-     * @param pojo : the pojo on which the method exits.
-     * @param method : exiting method.
-     * @param returnedObj : the returned object (boxed for primitive type)
+     * The default implementation does nothing.
+     * @param pojo the pojo on which the method exits.
+     * @param method the exiting method.
+     * @param returnedObj the returned object (boxed for primitive type)
+     * @see MethodInterceptor#onExit(Object, Method, Object)
      */
     public void onExit(Object pojo, Method method, Object returnedObj) { 
         // Nothing to do in the default implementation
     }
     
     /**
-     * This method is called when the execution throw an exception in the given method.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
-     * @param throwable : the thrown exception
+     * Callback method called when an error occurs.
+     * This method is called when the execution throws an exception 
+     * in the given method.
+     * The default implementation does nothing.
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
+     * @param throwable the thrown exception
+     * @see org.apache.felix.ipojo.MethodInterceptor#onError(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)
      */
     public void onError(Object pojo, Method method, Throwable throwable) {
         // Nothing to do in the default implementation
     }
     
     /**
-     * This method is called when the execution of a method will terminate : 
+     * Callback method called when the execution of a method will terminate : 
      * just before to throw an exception or before to return.
-     * OnError or OnExit was already called.
-     * @param pojo : the pojo on which the method was accessed.
-     * @param method : invoked method.
+     * {@link MethodInterceptor#onExit(Object, Method, Object)} or
+     * {@link MethodInterceptor#onError(Object, Method, Throwable)} 
+     * were already called.
+     * This default implementation does nothing.
+     * @param pojo the pojo on which the method was accessed.
+     * @param method the invoked method.
      */
     public void onFinally(Object pojo, Method method) {
         // Nothing to do in the default implementation
     }
     
     /**
-     * This method is called when an instance of the component is created, but
+     * Callback method called when an instance of the component is created, but
      * before someone can use it.
-     * @param instance : the created instance
+     * The default implementation does nothing.
+     * @param instance the created instance
      */
     public void onCreation(Object instance) { 
         // Nothing to do in the default implementation
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java
index ff951c5..aa56992 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ServiceContext.java
@@ -27,99 +27,123 @@
 import org.osgi.framework.ServiceRegistration;
 
 /**
- * A service context give the access the a service broker. All service
- * interaction should use this service context.
- * 
+ * A service context is the facade of a service registry. 
+ * It gives the access to a service broker. All service
+ * interactions should use a service context to garanty
+ * the service isolation.
+ * This class is a subset of {@link BundleContext} methods.
+ * (methods implying interactions with the service registry).
+ * So, refer to this class for further information.
+ * @see BundleContext
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface ServiceContext extends BundleContext {
 
     /**
-     * Add a service listener.
-     * @param listener : the service listener to add.
-     * @param filter : the LDAP filter
-     * @throws InvalidSyntaxException : occurs when the LDAP filter is malformed
+     * Adds a service listener.
+     * The listener is added to this service context.
+     * So only services from this context will be tracked.
+     * @param listener the service listener to add.
+     * @param filter the LDAP filter
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener, java.lang.String)
      */
     void addServiceListener(ServiceListener listener, String filter) throws InvalidSyntaxException;
 
     /**
-     * Add a service listener.
-     * @param listener : the service listener to add.
+     * Adds a service listener.
+     * The listener is added to this service context.
+     * So only services from this context will be tracked.
+     * @param listener the service listener to add.
      * @see org.osgi.framework.BundleContext#addServiceListener(org.osgi.framework.ServiceListener)
      */
     void addServiceListener(ServiceListener listener);
 
     /**
-     * Get the service references matching with the given query.
-     * @param clazz : Required interface
-     * @param filter : LDAP filter
-     * @return the array of available service reference
-     * @throws InvalidSyntaxException : occurs if the LDAP filter is malformed
+     * Gets the service references matching with the given query.
+     * The query is executed inside this service context.
+     * @param clazz the required interface
+     * @param filter a LDAP filter
+     * @return the array of available service references or <code>null</code>
+     * if no providers are available.
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#getAllServiceReferences(java.lang.String, java.lang.String)
      */
     ServiceReference[] getAllServiceReferences(String clazz, String filter) throws InvalidSyntaxException;
 
     /**
-     * Get a service object.
-     * @param reference : the required service reference 
+     * Gets a service object.
+     * The given service reference must comes from this
+     * service context.
+     * @param reference the required service reference 
      * @return the service object or null if the service reference is no more valid or if the service object is not accessible
      * @see org.osgi.framework.BundleContext#getService(org.osgi.framework.ServiceReference)
      */
     Object getService(ServiceReference reference);
 
     /**
-     * Get a service reference for the given interface.
-     * @param clazz : the required interface name
-     * @return a service reference on a available provider or null if no provider available
+     * Gets a service reference for the given interface.
+     * The query is executed inside this service context.
+     * @param clazz the required interface name
+     * @return a service reference on a available provider or 
+     * <code>null</code> if no providers are available
      * @see org.osgi.framework.BundleContext#getServiceReference(java.lang.String)
      */
     ServiceReference getServiceReference(String clazz);
 
     /**
-     * Get service reference list for the given query.
+     * Gets service reference list for the given query.
+     * The query is executed inside this service context.
      * @param clazz : the name of the required service interface
      * @param filter : LDAP filter to apply on service provider
-     * @return : the array of consistent service reference or null if no available provider
-     * @throws InvalidSyntaxException : occurs if the LDAP filter is malformed
+     * @return : the array of consistent service reference or <code>null</code>
+     * if no available providers
+     * @throws InvalidSyntaxException if the LDAP filter is malformed
      * @see org.osgi.framework.BundleContext#getServiceReferences(java.lang.String, java.lang.String)
      */
     ServiceReference[] getServiceReferences(String clazz, String filter) throws InvalidSyntaxException;
 
     /**
-     * Register a service.
-     * @param clazzes : interfaces provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
+     * Registers a service inside this service context.
+     * This service is then isolated inside this context.
+     * @param clazzes the interfaces provided by the service.
+     * @param service the service object.
+     * @param properties service properties to publish
      * @return the service registration for this service publication.
+     * This service registration is attached to the current service context,
+     * and does not have any meaning in other contexts.
      * @see org.apache.felix.ipojo.ServiceContext#registerService(java.lang.String[], java.lang.Object, java.util.Dictionary)
      */
     ServiceRegistration registerService(String[] clazzes, Object service, Dictionary properties);
 
     /**
-     * Register a service.
-     * @param clazz : interface provided by the service.
-     * @param service : the service object.
-     * @param properties : service properties.
-     * @return the service registration for this service publication.
+     * Registers a service inside this service context.
+     * This service is then isolated inside this context.
+     * @param clazz the interface provided by the service.
+     * @param service the service object.
+     * @param properties service properties to publish.
+     * @return the service registration for this service publication. 
+     * This service registration is attached to the current service context,
+     * and does not have any meaning in other contexts.
      * @see org.osgi.framework.BundleContext#registerService(java.lang.String, java.lang.Object, java.util.Dictionary)
      */
     ServiceRegistration registerService(String clazz, Object service, Dictionary properties);
 
     /**
-     * Remove a service listener.
-     * @param listener : the listener to remove
+     * Removes a service listener.
+     * The listener must be registered inside this service context.
+     * @param listener the listener to remove
      * @see org.osgi.framework.BundleContext#removeServiceListener(org.osgi.framework.ServiceListener)
      */
     void removeServiceListener(ServiceListener listener);
 
     /**
-     * Unget the service reference.
-     * @param reference : the reference to unget
-     * @return true if you are the last user of the reference
+     * Ungets the service reference.
+     * The service reference must comes from this service context.
+     * @param reference the reference to unget
+     * @return <code>true</code> if you are the last user of the reference.
      * @see org.osgi.framework.BundleContext#ungetService(org.osgi.framework.ServiceReference)
      */
     boolean ungetService(ServiceReference reference);
 
-
 }
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java
index b6aff61..dab2c99 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/UnacceptableConfiguration.java
@@ -20,7 +20,9 @@
 
 /**
  * UnacceptableConfiguration occurs when a factory refuses to create an
- * instance.
+ * instance. This exception is thrown when the instance configuration does not
+ * specify a value for a required property or when the configuration tries to override
+ * the value of an immutable property
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
@@ -32,8 +34,8 @@
     private static final long serialVersionUID = 2998931848886223965L;
 
     /**
-     * Constructor.
-     * @param message : message indicating the error.
+     * Creates an UnacceptableConfiguration.
+     * @param message : message about the error.
      */
     public UnacceptableConfiguration(String message) {
         super(message);
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java
index 0274171..223c51e 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/architecture/Architecture.java
@@ -20,14 +20,15 @@
 
 /**
  * Architecture service.
- * Allows to have information on the component.
+ * This service allows collecting information on the component instance,
+ * such as its state, plugged handlers ...
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface Architecture {
 
     /**
-     * Return the description of the instance.
-     * @return : the current component instance description
+     * Returns the description of the instance.
+     * @return the current component instance description
      */
     InstanceDescription getInstanceDescription();
 
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java
index bc272d0..db8bc98 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/FieldMetadata.java
@@ -21,26 +21,29 @@
 import org.apache.felix.ipojo.metadata.Element;
 
 /**
- * A Field Metadata represent a field of an implementation class.
- * This class allow to avoid reflection to get the type and the name of a field.
+ * A Field Metadata represents a field of the implementation class.
+ * This class avoids using reflection to get the type and the name of a field.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class FieldMetadata {
     
     /**
-     * Name of the field.
+     * The name of the field.
      */
     private String m_name;
     
     /**
-     * Type of the field. 
+     * The yype of the field. 
      */
     private String m_type;
     
     /**
-     * Constructor.
-     * @param metadata : field manipulation element.
+     * Creates a field metadata.
+     * This constructor is used when creating the {@link PojoMetadata}
+     * object.
+     * @param metadata the field manipulation element from Manipulation
+     * Metadata.
      */
     FieldMetadata(Element metadata) {
         m_name = metadata.getAttribute("name");
@@ -48,9 +51,12 @@
     }
     
     /**
-     * Constructor.
-     * @param field : field name.
-     * @param type : type of the field.
+     * Creates a field metadata.
+     * This constructor can be used to avoid using {@link PojoMetadata}.
+     * Be care that creating such {@link FieldMetadata} does not assert its 
+     * presence in the implementation class.
+     * @param field the field name.
+     * @param type the type of the field.
      */
     public FieldMetadata(String field, String type) {
         m_name = field;
@@ -62,10 +68,11 @@
     public String getFieldType() { return m_type; }
     
     /**
-     * Get the 'reflective' type of the given type.
+     * Gets the 'reflective' type of the given type.
      * The reflective type is the type used by the Java Reflection API.
-     * @param type : the type to analyze to find the Java reflective type.
-     * @return : the reflective type corresponding to this field.
+     * More precisely this method handles the array cases 
+     * @param type the type to analyze to find the Java reflective type.
+     * @return the reflective type corresponding to this field.
      */
     public static String getReflectionType(String type) {
         // Primitive Array 
@@ -83,9 +90,9 @@
     }
     
     /**
-     * Get the internal notation for primitive type.
-     * @param string : String form of the type
-     * @return the internal notation or null if not found
+     * Gets the internal notation for primitive type.
+     * @param string the String form of the type
+     * @return the internal notation or <code>null</code> if not found
      */
     public static String getInternalPrimitiveType(String string) {
         if (string.equalsIgnoreCase("boolean")) {
@@ -116,9 +123,10 @@
     }
     
     /**
-     * Get the iPOJO primitive type from the given primitive class.
-     * @param clazz : a primitive class
-     * @return the primitive type.
+     * Gets the iPOJO primitive type from the given primitive class.
+     * @param clazz the class of the primitive type
+     * @return the iPOJO primitive type name or <code>null</code> if
+     * not found.
      */
     public static String getPrimitiveTypeByClass(Class clazz) {
         if (clazz.equals(Boolean.TYPE)) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java
index 3680d38..abac730 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ManifestMetadataParser.java
@@ -29,21 +29,24 @@
 import org.apache.felix.ipojo.metadata.Element;
 
 /**
- * Manifest Metadata parser. Read a manifest file and construct metadata
+ * The Manifest Metadata parser reads a manifest file and builds
+ * the iPOJO metadata ({@link Element} / {@link Attribute} ) structure.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ManifestMetadataParser {
 
     /**
-     * Element list.
+     * The element list.
+     * Contains the element found in the parsed header.
      */
     private Element[] m_elements = new Element[0];
 
     /**
-     * Get the array of component type metadata.
+     * Gets the array of component type metadata.
      * @return the component metadata (composite & component).
-     * @throws ParseException when a parsing error occurs
+     * An empty array is returned if no component type declaration.
+     * @throws ParseException if a parsing error occurs
      */
     public Element[] getComponentsMetadata() throws ParseException {
         Element[] elems = m_elements[0].getElements();
@@ -57,9 +60,9 @@
     }
 
     /**
-     * Get the array of instance configuration described in the metadata.
-     * @return the instances list.
-     * @throws ParseException : if the metadata cannot be parsed successfully
+     * Gets the array of instance configuration described in the metadata.
+     * @return the instances list or <code>null</code> if no instance configuration.
+     * @throws ParseException if the metadata cannot be parsed successfully
      */
     public Dictionary[] getInstances() throws ParseException {
         Element[] configs = m_elements[0].getElements("instance");
@@ -74,11 +77,12 @@
     }
 
     /**
-     * Parse an Element to get a dictionary.
-     * 
-     * @param instance : the Element describing an instance.
-     * @return : the resulting dictionary
-     * @throws ParseException : occurs when a configuration cannot be parse correctly.
+     * Parses an Element to create an instance configuration dictionary.
+     * The 'name' attribute of the instance declaration is mapped
+     * to the 'instance.name' property. 
+     * @param instance the Element describing an instance.
+     * @return the resulting dictionary
+     * @throws ParseException if a configuration cannot be parse correctly.
      */
     private Dictionary parseInstance(Element instance) throws ParseException {
         Dictionary dict = new Properties();
@@ -103,10 +107,11 @@
     }
 
     /**
-     * Parse a property.
-     * @param prop : the current element to parse
-     * @param dict : the dictionary to populate
-     * @throws ParseException : occurs if the property cannot be parsed correctly
+     * Parses an instance property.
+     * This method is recursive to handle complex properties.
+     * @param prop the current element to parse
+     * @param dict the dictionary to populate (the future instance configuration)
+     * @throws ParseException if the property cannot be parsed correctly
      */
     private void parseProperty(Element prop, Dictionary dict) throws ParseException {
         // Check that the property has a name
@@ -148,10 +153,11 @@
     }
     
     /**
-     * Parses a complex property. This property will be build as a Dictionary.
-     * @param prop Element to parse.
+     * Parses a complex property. 
+     * This property will be built as a {@link Dictionary}.
+     * @param prop the Element to parse.
      * @return the resulting dictionary
-     * @throws ParseException occurs when an internal property is incorrect. 
+     * @throws ParseException if an internal property is incorrect. 
      */
     private Dictionary parseDictionary(Element prop) throws ParseException {
      // Check if there is 'property' elements
@@ -169,11 +175,12 @@
     }
     
     /**
-     * Parses a complex property. This property will be built as a Map.
-     * The used Map implementation is HashMap.
+     * Parses a complex property. 
+     * This property will be built as a {@link Map}.
+     * The used {@link Map} implementation is {@link HashMap}.
      * @param prop the property to parse
      * @return the resulting Map
-     * @throws ParseException occurs when an internal property is incorrect.
+     * @throws ParseException if an internal property is incorrect.
      */
     private Map parseMap(Element prop) throws ParseException {
         // Check if there is 'property' elements
@@ -190,11 +197,12 @@
     }
     
     /**
-     * Parses a complex property. This property will be built as a List.
-     * The used Map implementation is ArrayList. The order or element is kept.
+     * Parses a complex property. This property will be built as a {@link List}.
+     * The used {@link List} implementation is {@link ArrayList}. 
+     * The order of elements is kept.
      * @param prop the property to parse
      * @return the resulting List
-     * @throws ParseException occurs when an internal property is incorrect.
+     * @throws ParseException if an internal property is incorrect.
      */
     private List parseList(Element prop) throws ParseException {
         Element[] subProps = prop.getElements("property");
@@ -212,9 +220,10 @@
     
     /**
      * Parse a property.
-     * @param prop : the current element to parse
-     * @param map : the map to populate
-     * @throws ParseException : occurs if the property cannot be parsed correctly
+     * This methods handles complex properties.
+     * @param prop the current element to parse
+     * @param map the map to populate
+     * @throws ParseException if the property cannot be parsed correctly
      */
     private void parseProperty(Element prop, Map map) throws ParseException {
         // Check that the property has a name
@@ -255,12 +264,13 @@
     }
 
     /**
-     * Parse an anonymous property. An anonymous property is a property with no name.
+     * Parse an anonymous property.
+     * An anonymous property is a property with no name.
      * An anonymous property can be simple (just a value) or complex (i.e. a map, a dictionary 
      * a list or an array).
      * @param prop the property to parse
      * @param list the list to populate with the resulting property
-     * @throws ParseException occurs when an internal property cannot be parse correctly
+     * @throws ParseException if an internal property cannot be parse correctly
      */
     private void parseAnonymousProperty(Element prop, List list) throws ParseException {
         // Check that the property has a name
@@ -336,9 +346,8 @@
     }
 
     /**
-     * Add an element to the list.
-     * 
-     * @param elem : the element to add
+     * Adds an element to the {@link ManifestMetadataParser#m_elements} list.
+     * @param elem the the element to add
      */
     private void addElement(Element elem) {
         if (m_elements == null) {
@@ -352,8 +361,7 @@
     }
 
     /**
-     * Remove an element to the list.
-     * 
+     * Removes an element from the {@link ManifestMetadataParser#m_elements} list.
      * @return an element to remove
      */
     private Element removeLastElement() {
@@ -375,10 +383,13 @@
     }
 
     /**
-     * Parse the given dictionary and create the instance managers.
-     * 
-     * @param dict : the given headers of the manifest file
-     * @throws ParseException : if any error occurs
+     * Looks for the <code>iPOJO-Components</code> header
+     * in the given dictionary. Then, initializes the 
+     * {@link ManifestMetadataParser#m_elements} list (adds the
+     * <code>iPOJO</code> root element) and parses the contained
+     * component type declarations and instance configurations.
+     * @param dict the given headers of the manifest file
+     * @throws ParseException if any error occurs
      */
     public void parse(Dictionary dict) throws ParseException {
         String componentClassesStr = (String) dict.get("iPOJO-Components");
@@ -388,10 +399,12 @@
     }
 
     /**
-     * Parse the given header and create the instance managers.
-     * 
-     * @param header : the given header of the manifest file
-     * @throws ParseException : if any error occurs
+     * Parses the given header, initialized the 
+     * {@link ManifestMetadataParser#m_elements} list 
+     * (adds the <code>iPOJO</code> element) and parses 
+     * contained component type declarations and instance configurations.
+     * @param header the given header of the manifest file
+     * @throws ParseException if any error occurs
      */
     public void parseHeader(String header) throws ParseException {
         // Add the ipojo element inside the element list
@@ -400,11 +413,13 @@
     }
 
     /**
-     * Parse the metadata from the string given in argument.
-     * 
-     * @param metadata : the metadata to parse
-     * @return Element : the root element resulting of the parsing
-     * @throws ParseException : if any error occurs
+     * Parses the metadata from the string given in argument.
+     * This methods creates a new {@link ManifestMetadataParser} object
+     * and calls the {@link ManifestMetadataParser#parseElements(String)}
+     * method. The parsing must result as a tree (only one root element).
+     * @param metadata the metadata to parse
+     * @return Element the root element resulting of the parsing
+     * @throws ParseException if any error occurs
      */
     public static Element parse(String metadata) throws ParseException {
         ManifestMetadataParser parser = new ManifestMetadataParser();
@@ -416,10 +431,15 @@
     }
     
     /**
-     * Parse the metadata from the given header string.
-     * @param header : the header to parse
-     * @return Element : the root element resulting of the parsing
-     * @throws ParseException : if any error occurs
+     * Parses the metadata from the given header string.
+     * This method creates a new {@link ManifestMetadataParser} object and then
+     * creates the <code>iPOJO</code> root element, parses content elements
+     * (component types and instances declarations), and returns the resulting 
+     * {@link Element} / {@link Attribute} structure. The parsed string
+     * must be a tree (only one root element).
+     * @param header the header to parse
+     * @return Element the root element resulting of the parsing
+     * @throws ParseException if any error occurs
      */
     public static Element parseHeaderMetadata(String header) throws ParseException {
         ManifestMetadataParser parser = new ManifestMetadataParser();
@@ -432,9 +452,10 @@
     }
 
     /**
-     * Parse the given string.
-     * 
-     * @param elems : the string to parse
+     * Parses the given string.
+     * This methods populates the {@link ManifestMetadataParser#m_elements}
+     * list.
+     * @param elems the string to parse
      */
     private void parseElements(String elems) {
         char[] string = elems.toCharArray();
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java
index 302c2d4..e92363c 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/MethodMetadata.java
@@ -23,31 +23,30 @@
 import org.apache.felix.ipojo.metadata.Element;
 
 /**
- * A Method Metadata represent a method from the implementation class.
- * This class allow to get information about a method : name, arguments, return type...
- * 
+ * A Method Metadata represents a method from the implementation class.
+ * This class allows getting information about a method : name, arguments, return type...
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class MethodMetadata {
 
     /**
-     * Name of the method.
+     * The name of the method.
      */
     private String m_name;
 
     /**
-     * Argument type array. 
+     * The argument type array. 
      */
     private String[] m_arguments = new String[0];
 
     /**
-     * Returned type. 
+     * The returned type. 
      */
     private String m_return = "void";
 
     /**
-     * Constructor.
-     * @param metadata : method manipulation element.
+     * Creates a Method Metadata.
+     * @param metadata the method manipulation element.
      */
     MethodMetadata(Element metadata) {
         m_name = metadata.getAttribute("name");
@@ -74,7 +73,9 @@
     }
 
     /**
-     * Get the method unique identifier. For internal usage only.
+     * Gets the method unique identifier. For internal usage only.
+     * A method identifier is a unique string that can be a java field
+     * that identify the method.
      * @return the method identifier.
      */
     public String getMethodIdentifier() {
@@ -94,8 +95,8 @@
     }
 
     /**
-     * Compute the method id for the given method. 
-     * @param method : Method object.
+     * Computes the method id for the given Method object. 
+     * @param method the Method object.
      * @return the method id.
      */
     public static String computeMethodId(Method method) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java
index e28c559..1a1db2d 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseException.java
@@ -19,7 +19,7 @@
 package org.apache.felix.ipojo.parser;
 
 /**
- * Exceptions thrown by parsers.
+ * Exception thrown by parsers.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ParseException extends Exception {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java
index 4cba781..a2227e5 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/ParseUtils.java
@@ -23,16 +23,16 @@
 import java.util.StringTokenizer;
 
 /**
- * Parse Utility Methods.
- * 
+ * Parser Utility Methods.
+ * This class contains helper method to parse iPOJO metadata.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public final class ParseUtils {
 
     /**
-     * Parse the string form of an array as {a, b, c}.
-     * 
-     * @param str : the string form
+     * Parses the iPOJO string form of an array as {a, b, c}
+     * or [a, b, c].
+     * @param str the string form
      * @return the resulting string array
      */
     public static String[] parseArrays(String str) {
@@ -55,10 +55,10 @@
     }
     
     /**
-     * Parse the string form of an array as {a, b, c}.
-     * 
-     * @param str : the string form
-     * @return the resulting string array
+     * Parses the string form of an array as {a, b, c}
+     * or [a, b, c] as a list.
+     * @param str the string form
+     * @return the resulting list
      */
     public static List parseArraysAsList(String str) {
         return Arrays.asList(parseArrays(str));
@@ -68,9 +68,9 @@
      * Split method. 
      * This method is equivalent of the String.split in java 1.4
      * The result array contains 'trimmed' String
-     * @param toSplit : String to split
-     * @param separator : separator
-     * @return the token array 
+     * @param toSplit the String to split
+     * @param separator the separator
+     * @return the split array 
      */
     public static String[] split(String toSplit, String separator) {
         StringTokenizer tokenizer = new StringTokenizer(toSplit, separator);
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java
index a45d066..3030605 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/parser/PojoMetadata.java
@@ -23,39 +23,41 @@
 
 /**
  * Manipulation Metadata allows getting information about the implementation class
- * without doing reflection. 
- * 
+ * without using reflection such as implemented interfaces, super class,
+ * methods and fields. 
+ * This method allows getting object to register {@link org.apache.felix.ipojo.FieldInterceptor} and
+ * {@link org.apache.felix.ipojo.MethodInterceptor}.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class PojoMetadata {
     
     /**
-     * List of implemented interfaces.
+     * The list of implemented interfaces.
      */
     private String[] m_interfaces = new String[0];
     
     /**
-     * List of fields.
+     * The list of fields.
      */
     private FieldMetadata[] m_fields = new FieldMetadata[0];
     
     /**
-     * List of methods. 
+     * The list of methods. 
      */
     private MethodMetadata[] m_methods = new MethodMetadata[0];
 
     /**
-     * Super class (if not java.lang.object).
+     * The Super class (if <code>null</code> for {@link Object}).
      */
     private String m_super;
     
     
     /**
-     * Constructor.
+     * Creates Pojo metadata.
      * Manipulation Metadata object are created from component type metadata by
      * parsing manipulation metadata.
-     * @param metadata : component type metadata
-     * @throws ConfigurationException : the manipulation metadata cannot be found
+     * @param metadata the component type metadata
+     * @throws ConfigurationException if the manipulation metadata cannot be found
      */
     public PojoMetadata(Element metadata) throws ConfigurationException {
         Element[] elems = metadata.getElements("manipulation", "");
@@ -87,9 +89,9 @@
     public String[] getInterfaces() { return m_interfaces; }
     
     /**
-     * Get the field metadata for the given name. 
-     * @param name : name of the field
-     * @return the corresponding field metadata or null if not found
+     * Gets the field metadata for the given name. 
+     * @param name : the name of the field
+     * @return the corresponding field metadata or <code>null</code> if not found
      */
     public FieldMetadata getField(String name) { 
         for (int i = 0; i < m_fields.length; i++) {
@@ -99,10 +101,10 @@
     }
     
     /**
-     * Get the field metadata for the given name and type. 
-     * @param name : name of the field
-     * @param type : type of the field
-     * @return the corresponding field metadata or null if not found
+     * Gets the field metadata for the given name and type. 
+     * @param name : the name of the field
+     * @param type : the type of the field
+     * @return the corresponding field metadata or <code>null</code> if not found
      */
     public FieldMetadata getField(String name, String type) { 
         for (int i = 0; i < m_fields.length; i++) {
@@ -112,9 +114,12 @@
     }
     
     /**
-     * Check if the given interface name is implemented.
-     * @param itf : interface to check.
-     * @return true if the implementation class implement the given interface.
+     * Checks if the given interface name is implemented.
+     * This methods checks on interface directly implemented
+     * by the implementation class.
+     * @param itf the interface to check.
+     * @return <code>true</code> if the implementation class implements
+     * the given interface.
      */
     public boolean isInterfaceImplemented(String itf) {
         for (int i = 0; i < m_interfaces.length; i++) {
@@ -124,11 +129,12 @@
     }
     
     /**
-     * Get the MethodMetadata corresponding to the method
-     * (contained in the implementation class) to given name.
-     * If several method match, the first one is returned.
-     * @param name : name of the method to look for.
-     * @return the Method Metadate or null if not found
+     * Gets the MethodMetadata corresponding to the method
+     * (contained in the implementation class) with
+     * the given name.
+     * If several methods match, the first one is returned.
+     * @param name the name of the method to find.
+     * @return the method metadata object or <code>null</code> if not found
      */
     public MethodMetadata getMethod(String name) {
         for (int i = 0; i < m_methods.length; i++) {
@@ -138,11 +144,11 @@
     }
     
     /**
-     * Get the MethodMetadata list corresponding to the method
+     * Gets the MethodMetadata list corresponding to the method
      * (contained in the implementation class) to given name.
      * All methods contained in the implementation class matching 
      * with the name are in the returned list.
-     * @param name : name of the method to look for.
+     * @param name the name of the method to look for.
      * @return the Method Metadata array or an empty array if not found
      */
     public MethodMetadata[] getMethods(String name) {
@@ -163,12 +169,12 @@
     }
     
     /**
-     * Get the MethodMetadata corresponding to the method
+     * Gets the MethodMetadata corresponding to the method
      * (contained in the implementation class) to given name 
      * and argument types.
-     * @param name : name of the method to look for.
-     * @param types : array of the argument types of the method 
-     * @return the Method Metadate or null if not found
+     * @param name the name of the method to look for.
+     * @param types the array of the argument types of the method 
+     * @return the Method Metadata or <code>null</code> if not found
      */
     public MethodMetadata getMethod(String name, String[] types) {
         for (int i = 0; i < m_methods.length; i++) {
@@ -186,8 +192,10 @@
     }
         
      /**
-      * Add a method to the list.
-     * @param method : Method Metadata to add.
+     * Adds a method to the list.
+     * This method is used during the creation of the {@link PojoMetadata}
+     * object.
+     * @param method the Method Metadata to add.
      */
     private void addMethod(MethodMetadata method) {
         for (int i = 0; (m_methods != null) && (i < m_methods.length); i++) {
@@ -207,8 +215,10 @@
     }
         
      /**
-      * Add a field to the list.
-     * @param field : the Field Metadata to add.
+     * Adds a field to the list.
+     * This method is used during the creation of the {@link PojoMetadata}
+     * object.
+     * @param field the Field Metadata to add.
      */
     private void addField(FieldMetadata field) {
         for (int i = 0; (m_fields != null) && (i < m_fields.length); i++) {
@@ -228,8 +238,10 @@
     }
         
     /**
-     * Add the interface to the list.
-     * @param itf : the interface name to add.
+     * Adds the interface to the list.
+     * This method is used during the creation of the {@link PojoMetadata}
+     * object.
+     * @param itf the interface name to add.
      */
     private void addInterface(String itf) {
         for (int i = 0; (m_interfaces != null) && (i < m_interfaces.length); i++) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java
index 04d4a5d..5cede5a 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Callback.java
@@ -26,42 +26,52 @@
 import org.apache.felix.ipojo.parser.MethodMetadata;
 
 /**
- * A callback allows calling a method on the component instances.
+ * A callback allows invoking a method on a POJO.
+ * This class supports both public, protected and private methods of the
+ * implementation class. This class also supports public method from super class.
+ * The {@link Method} object is computed once and this computation is delayed
+ * to the first invocation.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Callback {
 
     /**
-     * Method object.
+     * The method object.
+     * Computed at the first call.
      */
     protected Method m_methodObj;
 
     /**
-     * Name of the method to call.
+     * The name of the method to call.
      */
     private String m_method;
 
     /**
      * Is the method a static method ?
+     * This implies calling the method on <code>null</code>
      */
     private boolean m_isStatic;
 
     /**
-     * Reference on the instance manager.
+     * The reference on the instance manager.
+     * Used to get POJO objects.
      */
     private InstanceManager m_manager;
 
     /**
-     * Argument classes.
+     * The argument classes.
+     * This array contains the list of argument class names.
      */
     private String[] m_args;
 
     /**
-     * Callback constructor.
-     * @param method : the name of the method to call
-     * @param args : argument type name
-     * @param isStatic : is the method a static method
-     * @param manager : the instance manager of the component containing the method
+     * Creates a Callback.
+     * If the argument array is not null the reflection type are computed.
+     * @see {@link Callback#computeArguments(String[])}
+     * @param method the name of the method to call
+     * @param args the argument type name, or <code>null</code> if no arguments
+     * @param isStatic is the method a static method
+     * @param manager the instance manager of the component containing the method
      */
     public Callback(String method, String[] args, boolean isStatic, InstanceManager manager) {
         m_method = method;
@@ -73,11 +83,11 @@
     }
 
     /**
-     * Callback constructor.
-     * @param method : the name of the method to call
-     * @param args : argument classes
-     * @param isStatic : is the method a static method
-     * @param manager : the instance manager of the component containing the method
+     * Creates a Callback.
+     * @param method the the name of the method to call
+     * @param args the argument classes
+     * @param isStatic the is the method a static method
+     * @param manager the the instance manager of the component containing the method
      */
     public Callback(String method, Class[] args, boolean isStatic, InstanceManager manager) {
         m_method = method;
@@ -90,9 +100,10 @@
     }
 
     /**
-     * Constructor.
-     * @param method : Method Metadata obtain form manipulation metadata.
-     * @param manager : instance manager.
+     * Creates a Callback.
+     * @param method the {@link MethodMetadata} obtained from manipulation
+     * metadata ({@link PojoMetadata}).
+     * @param manager the instance manager.
      */
     public Callback(MethodMetadata method, InstanceManager manager) {
         m_isStatic = false;
@@ -102,8 +113,10 @@
     }
 
     /**
-     * Compute arguments of the method.
-     * @param args : arguments of the method.
+     * Computes arguments of the method.
+     * This method computes "reflection type" from given argument.
+     * @see FieldMetadata#getReflectionType(String)
+     * @param args the arguments of the method.
      */
     private void computeArguments(String[] args) {
         m_args = new String[args.length];
@@ -113,9 +126,9 @@
     }
 
     /**
-     * Search the looked method in the given method arrays.
-     * @param methods : method array in which we need to look
-     * @return the method object or null if not found
+     * Searches the {@link Method} in the given method arrays.
+     * @param methods the method array in which the method should be found
+     * @return the method object or <code>null</code> if not found
      */
     private Method searchMethodInMethodArray(Method[] methods) {
         for (int i = 0; i < methods.length; i++) {
@@ -140,8 +153,10 @@
     }
 
     /**
-     * Search the method object in the POJO by analyzing present method. The name of the method and the argument type are checked.
-     * @throws NoSuchMethodException : occurs when the method cannot be found either in the pojo class either in parent classes.
+     * Searches the {@link Method} object in the POJO by analyzing implementation
+     * class methods. The name of the method and the argument type are checked.
+     * @throws NoSuchMethodException if the method cannot be found either in the
+     * implementation class or in parent classes.
      */
     protected void searchMethod() throws NoSuchMethodException {
         Method[] methods = m_manager.getClazz().getDeclaredMethods();
@@ -163,35 +178,43 @@
     }
 
     /**
-     * Call the method.
-     * @return the result of the invocation, null for void method, the last result for multi-object instance
-     * @throws NoSuchMethodException : Method is not found in the class
-     * @throws InvocationTargetException : The method is not static
-     * @throws IllegalAccessException : The method can not be invoked
+     * Invokes the method without arguments.
+     * If several the instance contains several objects, the method is invoked
+     * on every objects.
+     * @return the result of the invocation, <code>null</code> for <code>void</code>
+     * method, the last result for multi-object instance
+     * @throws NoSuchMethodException if Method is not found in the class
+     * @throws InvocationTargetException if the method throws an exception
+     * @throws IllegalAccessException if the method can not be invoked
      */
     public Object call() throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         return call(new Object[0]);
     }
 
     /**
-     * Call the current callback method on the instance given in parameter.
-     * @param instance : instance on which call the callback
-     * @return the result of the invocation, null for void method
-     * @throws NoSuchMethodException : the method was not found
-     * @throws IllegalAccessException : the method cannot be called
-     * @throws InvocationTargetException : an error happens in the method
+     * Invokes the method without arguments.
+     * The method is invokes on the specified object.
+     * @param instance the instance on which call the callback
+     * @return the result of the invocation, <code>null</code> for
+     * <code>void</code> method
+     * @throws NoSuchMethodException if the method was not found
+     * @throws IllegalAccessException if the method cannot be called
+     * @throws InvocationTargetException if an error happens in the method
      */
     public Object call(Object instance) throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         return call(instance, new Object[0]);
     }
 
     /**
-     * Call the callback on the method with the argument given in parameter.
-     * @param arg : the parameters
-     * @return the result of the invocation, null for void method, the last result for multi-object instance
-     * @throws NoSuchMethodException : the callback method is not found
-     * @throws IllegalAccessException : the callback method cannot be called
-     * @throws InvocationTargetException : an error occurs inside the called method
+     * Invokes the method on every created objects with the specified
+     * arguments.
+     * @param arg the method arguments
+     * @return the result of the invocation, <code>null</code> for 
+     * <code>void</code> method, the last result for instance containing
+     * several objects.
+     * @throws NoSuchMethodException if the callback method is not found
+     * @throws IllegalAccessException if the callback method cannot be called
+     * @throws InvocationTargetException if an error is thrown by the called method
      */
     public Object call(Object[] arg) throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         if (m_methodObj == null) {
@@ -218,13 +241,15 @@
     }
 
     /**
-     * Call the callback on the method with the argument given in parameter and with the arguments given in parameter too.
-     * @param instance : instance on which call the callback
-     * @param arg : the argument array
-     * @return the result of the invocation, null for void method
-     * @throws NoSuchMethodException : the callback method is not found
-     * @throws IllegalAccessException : the callback method cannot be called
-     * @throws InvocationTargetException : an error occurs inside the called method
+     * Invokes the method on the given object with the specified
+     * arguments.
+     * @param instance the instance on which call the method
+     * @param arg the argument array
+     * @return the result of the invocation, <code>null</code> for 
+     * <code>void</code> method
+     * @throws NoSuchMethodException if the callback method is not found
+     * @throws IllegalAccessException if the callback method cannot be called
+     * @throws InvocationTargetException if an error is thrown by the called method
      */
     public Object call(Object instance, Object[] arg) throws NoSuchMethodException, IllegalAccessException, InvocationTargetException {
         if (m_methodObj == null) {
@@ -234,6 +259,10 @@
         return m_methodObj.invoke(instance, arg);
     }
 
+    /**
+     * Gets the method name.
+     * @return the method name
+     */
     public String getMethod() {
         return m_method;
     }
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java
index d308287..364f554 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyModel.java
@@ -24,6 +24,7 @@
 import java.util.List;
 
 import org.apache.felix.ipojo.ConfigurationException;
+import org.apache.felix.ipojo.ServiceContext;
 import org.apache.felix.ipojo.context.ServiceReferenceImpl;
 import org.apache.felix.ipojo.metadata.Element;
 import org.osgi.framework.BundleContext;
@@ -31,41 +32,53 @@
 import org.osgi.framework.ServiceReference;
 
 /**
- * Abstract dependency model. This class is the parent class of every service dependency. It manages the most part of dependency management. This
- * class creates an interface between the service tracker and the concrete dependency.
+ * Abstract dependency model.
+ * This class is the parent class of every service dependency. It manages the most 
+ * part of dependency management. This class creates an interface between the service
+ * tracker and the concrete dependency.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public abstract class DependencyModel implements TrackerCustomizer {
 
     /**
-     * Dependency state : BROKEN. A broken dependency cannot be fulfilled anymore. The dependency becomes broken when a used service disappears in the
-     * static binding policy.
+     * Dependency state : BROKEN.
+     * A broken dependency cannot be fulfilled anymore. The dependency becomes
+     * broken when a used service disappears in the static binding policy.
      */
     public static final int BROKEN = -1;
 
     /**
-     * Dependency state : UNRESOLVED. A dependency is unresolved if the dependency is not valid and no service providers are available.
+     * Dependency state : UNRESOLVED.
+     * A dependency is unresolved if the dependency is not valid and no service
+     * providers are available.
      */
     public static final int UNRESOLVED = 0;
 
     /**
-     * Dependency state : RESOLVED. A dependency is resolved if the dependency is optional or at least one provider is available.
+     * Dependency state : RESOLVED. 
+     * A dependency is resolved if the dependency is optional or at least one
+     * provider is available.
      */
     public static final int RESOLVED = 1;
 
     /**
-     * Binding policy : Dynamic. In this policy, services can appears and departs without special treatment.
+     * Binding policy : Dynamic. 
+     * In this policy, services can appears and departs without special treatment.
      */
     public static final int DYNAMIC_BINDING_POLICY = 0;
 
     /**
-     * Binding policy : Static. Once a service is used, if this service disappears the dependency becomes BROKEN. The instance needs to be recreated.
+     * Binding policy : Static. 
+     * Once a service is used, if this service disappears the dependency becomes
+     * {@link DependencyModel#BROKEN}. The instance needs to be recreated.
      */
     public static final int STATIC_BINDING_POLICY = 1;
 
     /**
-     * Binding policy : Dynamic-Priority. In this policy, services can appears and departs. However, once a service with a highest ranking (according
-     * to the used comparator) appears, this new service is re-injected.
+     * Binding policy : Dynamic-Priority. 
+     * In this policy, services can appears and departs. However, once a service
+     * with a highest ranking (according to the used comparator) appears, this 
+     * new service is re-injected.
      */
     public static final int DYNAMIC_PRIORITY_BINDING_POLICY = 2;
 
@@ -80,61 +93,71 @@
     private boolean m_optional;
 
     /**
-     * Required specification. Cannot change once set.
+     * The required specification.
+     * Cannot change once set.
      */
     private Class m_specification;
 
     /**
-     * Comparator to sort service references.
+     * The comparator to sort service references.
      */
     private Comparator m_comparator;
 
     /**
-     * LDAP filter object selecting service references form the set of providers providing the required specification.
+     * The LDAP filter object selecting service references 
+     * from the set of providers providing the required specification.
      */
     private Filter m_filter;
 
     /**
-     * Bundle context used by the dependency. (could be a service context).
+     * Bundle context used by the dependency.
+     * (may be a {@link ServiceContext}).
      */
     private BundleContext m_context;
 
     /**
-     * Listener object on which invoking the validate and invalidate methods.
+     * Listener object on which invoking the {@link DependencyStateListener#validate(DependencyModel)} 
+     * and {@link DependencyStateListener#invalidate(DependencyModel)} methods.
      */
     private final DependencyStateListener m_listener;
 
     /**
-     * Actual state of the dependency.
+     * The actual state of the dependency.
+     * {@link DependencyModel#UNRESOLVED} at the beginning.
      */
     private int m_state;
 
     /**
-     * Binding policy of the dependency.
+     * The Binding policy of the dependency.
      */
     private int m_policy = DYNAMIC_BINDING_POLICY;
 
     /**
-     * Service tracker used by this dependency.
+     * The tracker used by this dependency to track providers.
      */
     private Tracker m_tracker;
 
     /**
-     * List of matching service references. This list is a subset of tracked references. This set is compute according to the filter and the match
-     * method.
+     * The list of matching service references. This list is a 
+     * subset of tracked references. This set is computed according 
+     * to the filter and the {@link DependencyModel#match(ServiceReference)} method.
      */
     private final List m_matchingRefs = new ArrayList();
 
     /**
-     * Constructor.
-     * @param specification : required specification
-     * @param aggregate : is the dependency aggregate ?
-     * @param optional : is the dependency optional ?
-     * @param filter : LDAP filter
-     * @param comparator : comparator object to sort references
-     * @param policy : binding policy
-     * @param context : bundle context (or service context)
-     * @param listener : dependency lifecycle listener to notify from dependency state changes.
+     * Creates a DependencyModel.
+     * If the dependency has no comparator and follows the
+     * {@link DependencyModel#DYNAMIC_PRIORITY_BINDING_POLICY} policy
+     * the OSGi Service Reference Comparator is used. 
+     * @param specification the required specification
+     * @param aggregate is the dependency aggregate ?
+     * @param optional is the dependency optional ?
+     * @param filter the LDAP filter
+     * @param comparator the comparator object to sort references
+     * @param policy the binding policy
+     * @param context the bundle context (or service context)
+     * @param listener the dependency lifecycle listener to notify from dependency
+     * state changes.
      */
     public DependencyModel(Class specification, boolean aggregate, boolean optional, Filter filter, Comparator comparator, int policy,
             BundleContext context, DependencyStateListener listener) {
@@ -154,7 +177,9 @@
     }
 
     /**
-     * Open the tracking.
+     * Opens the tracking.
+     * This method computes the dependency state
+     * @see DependencyModel#computeDependencyState()
      */
     public void start() {
         m_tracker = new Tracker(m_context, m_specification.getName(), this);
@@ -163,7 +188,9 @@
     }
 
     /**
-     * Close the tracking.
+     * Closes the tracking.
+     * The dependency becomes {@link DependencyModel#UNRESOLVED}
+     * at the end of this method.
      */
     public void stop() {
         if (m_tracker != null) {
@@ -174,26 +201,33 @@
     }
 
     /**
-     * Is the reference set frozen (cannot change anymore) ? This method must be override by concrete dependency to support the static binding policy.
-     * This method is just used by default. The method must always return false for non-static dependency.
-     * @return true if the reference set is frozen.
+     * Is the reference set frozen (cannot change anymore)? 
+     * This method must be override by concrete dependency to support
+     * the static binding policy. In fact, this method allows optimizing
+     * the static dependencies to become frozen only when needed.
+     * This method returns <code>false</code> by default. 
+     * The method must always return <code>false</code> for non-static dependencies.
+     * @return <code>true</code> if the reference set is frozen.
      */
     public boolean isFrozen() {
         return false;
     }
 
     /**
-     * Does the service reference match ? This method must be override by concrete dependency if they need to advanced testing on service reference
-     * (that cannot be express in the LDAP filter). By default this method return true.
-     * @param ref : tested reference.
-     * @return true
+     * Does the service reference match ? This method must be override by
+     * concrete dependencies if they need advanced testing on service reference
+     * (that cannot be expressed in the LDAP filter). By default this method 
+     * returns <code>true</code>.
+     * @param ref the tested reference.
+     * @return <code>true</code> if the service reference matches.
      */
     public boolean match(ServiceReference ref) {
         return true;
     }
 
     /**
-     * Compute the actual dependency state.
+     * Computes the actual dependency state.
+     * This methods invokes the {@link DependencyStateListener}.
      */
     private void computeDependencyState() {
         if (m_state == BROKEN) { return; } // The dependency is broken ...
@@ -226,9 +260,10 @@
     }
 
     /**
-     * Service tracker adding service callback. We accept the service only if we aren't broken or frozen.
-     * @param ref : the new dependency.
-     * @return true if the reference must be tracked.
+     * Service tracker adding service callback. 
+     * It accepts the service only if the dependency isn't broken or frozen.
+     * @param ref the arriving service reference.
+     * @return <code>true</code> if the reference must be tracked.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#addingService(org.osgi.framework.ServiceReference)
      */
     public boolean addingService(ServiceReference ref) {
@@ -236,7 +271,9 @@
     }
 
     /**
-     * Service Tracker added service callback. If the service matches, manage the arrival.
+     * Service Tracker added service callback. 
+     * If the service matches (against the filter and the {@link DependencyModel#match(ServiceReference)},
+     * manages the provider arrival.
      * @param ref : new references.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#addedService(org.osgi.framework.ServiceReference)
      */
@@ -248,12 +285,12 @@
     }
     
     /**
-     * Check if the given service reference match the current filter.
+     * Checks if the given service reference match the current filter.
      * This method aims to avoid calling {@link Filter#match(ServiceReference)} 
-     * method when manipulating a composite reference. In fact, this method throws
+     * method when manipulating a composite reference. In fact, this method thrown
      * a {@link ClassCastException} on Equinox.
-     * @param ref : the service reference to check.
-     * @return true if the service reference matches.
+     * @param ref the service reference to check.
+     * @return <code>true</code> if the service reference matches.
      */
     private boolean matchAgainstFilter(ServiceReference ref) {
         boolean match = true;
@@ -269,9 +306,10 @@
     }
 
     /**
-     * Manage the arrival of a new service reference. The reference is valid and match the filter and the match method. This method has different
-     * behavior according to the binding policy.
-     * @param ref : the new reference
+     * Manages the arrival of a new service reference. 
+     * The reference is valid and matches the filter and the {@link DependencyModel#match(ServiceReference)}
+     * method. This method has different behavior according to the binding policy.
+     * @param ref the new reference
      */
     private void manageArrival(ServiceReference ref) {
 
@@ -314,9 +352,11 @@
     }
 
     /**
-     * Service tracker removed service callback. A service goes away. The depart need to be managed only if the reference was used.
-     * @param ref : leaving service reference
-     * @param arg1 : service object if the service was get
+     * Service tracker removed service callback. 
+     * A service provider goes away. The depart needs to be managed only if the 
+     * reference was used.
+     * @param ref the leaving service reference
+     * @param arg1 the service object if the service was already get
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#removedService(org.osgi.framework.ServiceReference, java.lang.Object)
      */
     public void removedService(ServiceReference ref, Object arg1) {
@@ -326,9 +366,9 @@
     }
 
     /**
-     * Manage the departure of a used service.
-     * @param ref : leaving service reference
-     * @param obj : service object if the service was get
+     * Manages the departure of a used service.
+     * @param ref the leaving service reference
+     * @param obj the service object if the service was get
      */
     private void manageDeparture(ServiceReference ref, Object obj) {
         // If we already get this service and the binding policy is static, the dependency becomes broken
@@ -359,10 +399,13 @@
     }
 
     /**
-     * Service tracker modified service callback. This method must handle if the modified service should be considered as a depart or an arrival.
-     * According to the dependency filter, a service can now match or can no match anymore.
-     * @param ref : modified reference
-     * @param arg1 : service object if already get.
+     * Service tracker modified service callback. 
+     * This method must handle if the modified service should be considered as 
+     * a depart or an arrival.
+     * According to the dependency filter, a service can now match or can no match 
+     * anymore.
+     * @param ref the modified reference
+     * @param arg1 the service object if already get.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#modifiedService(org.osgi.framework.ServiceReference, java.lang.Object)
      */
     public void modifiedService(ServiceReference ref, Object arg1) {
@@ -384,8 +427,9 @@
     }
 
     /**
-     * Get the next matching service reference.
-     * @return null if no more provider is available, else return the first reference from the matching set.
+     * Gets the next matching service reference.
+     * @return <code>null</code> if no more provider is available, 
+     * else returns the first reference from the matching set.
      */
     public ServiceReference getServiceReference() {
         synchronized (this) {
@@ -398,8 +442,9 @@
     }
 
     /**
-     * Get matching service references.
-     * @return the sorted (if a comparator is used) array of matching service references, null if no references are available.
+     * Gets matching service references.
+     * @return the sorted (if a comparator is used) array of matching service 
+     * references, <code>null</code> if no references are available.
      */
     public ServiceReference[] getServiceReferences() {
         synchronized (this) {
@@ -409,7 +454,8 @@
     }
 
     /**
-     * Get the list of currently used service references.
+     * Gets the list of currently used service references.
+     * If no service references, returns <code>null</code>
      * @return the list of used reference (according to the service tracker).
      */
     public List getUsedServiceReferences() {
@@ -435,7 +481,7 @@
     }
 
     /**
-     * Get the number of actual matching references.
+     * Gets the number of actual matching references.
      * @return the number of matching references
      */
     public int getSize() {
@@ -443,21 +489,25 @@
     }
 
     /**
-     * Concrete dependency callback. This method is called when a new service need to be re-injected in the underlying concrete dependency.
-     * @param ref : service reference to inject.
+     * Concrete dependency callback. 
+     * This method is called when a new service needs to be 
+     * re-injected in the underlying concrete dependency.
+     * @param ref the service reference to inject.
      */
     public abstract void onServiceArrival(ServiceReference ref);
 
     /**
-     * Concrete dependency callback. This method is called when a used service (already injected) is leaving.
-     * @param ref : the leaving service reference.
+     * Concrete dependency callback. 
+     * This method is called when a used service (already injected) is leaving.
+     * @param ref the leaving service reference.
      */
     public abstract void onServiceDeparture(ServiceReference ref);
 
     /**
-     * This method can be override by the concrete dependency to be notified of service modification. This modification is not an arrival or a
-     * departure.
-     * @param ref : modified service reference.
+     * This method can be override by the concrete dependency to be notified
+     * of service modification.
+     * This modification is not an arrival or a departure.
+     * @param ref the modified service reference.
      */
     public void onServiceModification(ServiceReference ref) {
         if (m_policy == DYNAMIC_PRIORITY_BINDING_POLICY) {
@@ -474,37 +524,41 @@
     }
 
     /**
-     * Concrete dependency callback. This method is called when the dependency is reconfigured and when this reconfiguration implies changes on the
-     * matching service set ( and by the way on the injected service).
-     * @param departs : service leaving the matching set.
-     * @param arrivals : service arriving in the matching set.
+     * Concrete dependency callback. 
+     * This method is called when the dependency is reconfigured and when this
+     * reconfiguration implies changes on the matching service set ( and by the
+     * way on the injected service).
+     * @param departs the service leaving the matching set.
+     * @param arrivals the service arriving in the matching set.
      */
     public abstract void onDependencyReconfiguration(ServiceReference[] departs, ServiceReference[] arrivals);
 
     /**
-     * Call the listener callback to notify the new state of the current dependency.
+     * Calls the listener callback to notify the new state of the current 
+     * dependency.
      */
     private void invalidate() {
         m_listener.invalidate(this);
     }
 
     /**
-     * Call the listener callback to notify the new state of the current dependency.
+     * Calls the listener callback to notify the new state of the current 
+     * dependency.
      */
     private void validate() {
         m_listener.validate(this);
     }
 
     /**
-     * Get the actual state of the dependency.
-     * @return : the state of the dependency.
+     * Gets the actual state of the dependency.
+     * @return the state of the dependency.
      */
     public int getState() {
         return m_state;
     }
 
     /**
-     * Get the tracked specification.
+     * Gets the tracked specification.
      * @return the Class object tracked by the dependency.
      */
     public Class getSpecification() {
@@ -512,8 +566,9 @@
     }
 
     /**
-     * Set the required specification of this service dependency. This operation is not supported if the dependency tracking has already begun.
-     * @param specification : required specification.
+     * Sets the required specification of this service dependency. 
+     * This operation is not supported if the dependency tracking has already begun.
+     * @param specification the required specification.
      */
     public void setSpecification(Class specification) {
         if (m_tracker == null) {
@@ -524,8 +579,9 @@
     }
 
     /**
-     * Set the filter of the dependency. This method recompute the matching set and call the onDependencyReconfiguration callback.
-     * @param filter : new LDAP filter.
+     * Sets the filter of the dependency. This method recomputes the
+     * matching set and call the onDependencyReconfiguration callback.
+     * @param filter the new LDAP filter.
      */
     public void setFilter(Filter filter) { //NOPMD
         m_filter = filter;
@@ -641,8 +697,9 @@
     }
 
     /**
-     * Return the dependency filter (String form).
-     * @return the String form of the LDAP filter used by this dependency, null if not set.
+     * Returns the dependency filter (String form).
+     * @return the String form of the LDAP filter used by this dependency, 
+     * <code>null</code> if not set.
      */
     public String getFilter() {
         if (m_filter == null) {
@@ -653,8 +710,9 @@
     }
 
     /**
-     * Set the aggregate attribute of the current dependency. If the tracking is open, it will call arrival and departure callbacks.
-     * @param isAggregate : new aggregate attribute value.
+     * Sets the aggregate attribute of the current dependency. 
+     * If the tracking is opened, it will call arrival and departure callbacks.
+     * @param isAggregate the new aggregate attribute value.
      */
     public synchronized void setAggregate(boolean isAggregate) {
         if (m_tracker == null) { // Not started ...
@@ -688,8 +746,8 @@
     }
 
     /**
-     * Set the optionality attribute of the current dependency.
-     * @param isOptional : the new optional attribute value.
+     * Sets the optionality attribute of the current dependency.
+     * @param isOptional the new optional attribute value.
      */
     public void setOptionality(boolean isOptional) {
         if (m_tracker == null) { // Not started ...
@@ -704,7 +762,7 @@
     }
 
     /**
-     * Return the used binding policy.
+     * Gets the used binding policy.
      * @return the current binding policy.
      */
     public int getBindingPolicy() {
@@ -712,7 +770,8 @@
     }
 
     /**
-     * Set the binding policy. Not yet supported.
+     * Sets the binding policy. 
+     * Not yet supported.
      */
     public void setBindingPolicy() {
         throw new UnsupportedOperationException("Binding Policy change is not yet supported");
@@ -726,8 +785,8 @@
     
     /**
      * Gets the used comparator name.
-     * Null if no comparator (i.e. OSGi one is used).
-     * @return the comparator class name or null if the dependency doesn't use a comparator.
+     * <code>Null</code> if no comparator (i.e. the OSGi one is used).
+     * @return the comparator class name or <code>null</code> if the dependency doesn't use a comparator.
      */
     public String getComparator() {
         if (m_comparator != null) {
@@ -738,8 +797,9 @@
     }
 
     /**
-     * Set the bundle context used by this dependency. This operation is not supported if the tracker is already opened.
-     * @param context : bundle context or service context to use
+     * Sets the bundle context used by this dependency.
+     * This operation is not supported if the tracker is already opened.
+     * @param context the bundle context or service context to use
      */
     public void setBundleContext(BundleContext context) {
         if (m_tracker == null) { // Not started ...
@@ -750,30 +810,33 @@
     }
 
     /**
-     * Get a service object for the given reference.
-     * @param ref : wanted service reference
-     * @return : the service object attached to the given reference
+     * Gets a service object for the given reference.
+     * @param ref the wanted service reference
+     * @return the service object attached to the given reference
      */
     public Object getService(ServiceReference ref) {
         return m_tracker.getService(ref);
     }
 
     /**
-     * Unget a used service reference.
-     * @param ref : reference to unget.
+     * Ungets a used service reference.
+     * @param ref the reference to unget.
      */
     public void ungetService(ServiceReference ref) {
         m_tracker.ungetService(ref);
     }
 
     /**
-     * Helper method parsing the comparator attribute and returning the comparator object. If the 'comparator' attribute is not set, this method
-     * returns null. If the 'comparator' attribute is set to 'osgi', this method returns the normal OSGi comparator. In other case, it tries to create
+     * Helper method parsing the comparator attribute and returning the
+     * comparator object. If the 'comparator' attribute is not set, this method
+     * returns null. If the 'comparator' attribute is set to 'osgi', this method 
+     * returns the normal OSGi comparator. In other case, it tries to create
      * an instance of the declared comparator class.
-     * @param dep : Element describing the dependency
-     * @param context : bundle context (to load the comparator class)
-     * @return the comparator object, null if not set.
-     * @throws ConfigurationException the comparator class cannot be load or the comparator cannot be instantiated correctly.
+     * @param dep the Element describing the dependency
+     * @param context the bundle context (to load the comparator class)
+     * @return the comparator object, <code>null</code> if not set.
+     * @throws ConfigurationException the comparator class cannot be load or the
+     * comparator cannot be instantiated correctly.
      */
     public static Comparator getComparator(Element dep, BundleContext context) throws ConfigurationException {
         Comparator cmp = null;
@@ -798,11 +861,11 @@
     }
 
     /**
-     * Load the given specification class.
-     * @param specification : specification class name to load
-     * @param context : bundle context
-     * @return : the class object for the given specification
-     * @throws ConfigurationException : the class cannot be loaded correctly.
+     * Loads the given specification class.
+     * @param specification the specification class name to load
+     * @param context the bundle context
+     * @return the class object for the given specification
+     * @throws ConfigurationException if the class cannot be loaded correctly.
      */
     public static Class loadSpecification(String specification, BundleContext context) throws ConfigurationException {
         Class spec = null;
@@ -815,11 +878,13 @@
     }
 
     /**
-     * Helper method parsing the binding policy. If the 'policy' attribute is not set in the dependency, the method returns the 'DYNAMIC BINDING
-     * POLICY'. Accepted policy values are : dynamic, dynamic-priority and static.
-     * @param dep : Element describing the dependency
-     * @return : the policy attached to this dependency
-     * @throws ConfigurationException : an unknown biding policy was described.
+     * Helper method parsing the binding policy. 
+     * If the 'policy' attribute is not set in the dependency, the method returns 
+     * the 'DYNAMIC BINDING POLICY'. Accepted policy values are : dynamic, 
+     * dynamic-priority and static.
+     * @param dep the Element describing the dependency
+     * @return the policy attached to this dependency
+     * @throws ConfigurationException if an unknown binding policy was described.
      */
     public static int getPolicy(Element dep) throws ConfigurationException {
         String policy = dep.getAttribute("policy");
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java
index 5131337..a72409b 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/DependencyStateListener.java
@@ -20,20 +20,20 @@
 
 
 /**
- * This interface allows a class to be notified of dependency state changes.
+ * This interface allows a class to be notified of service dependency state changes.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface DependencyStateListener {
 
     /**
      * The given dependency becomes valid.
-     * @param dependency : dependency becoming valid.
+     * @param dependency the dependency becoming valid.
      */
     void validate(DependencyModel dependency);
     
     /**
      * The given dependency becomes invalid.
-     * @param dependency : dependency becoming invalid.
+     * @param dependency the dependency becoming invalid.
      */
     void invalidate(DependencyModel dependency);
 }
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java
index 0cde723..5c8a2f8 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Logger.java
@@ -23,58 +23,60 @@
 import org.osgi.service.log.LogService;
 
 /**
- * iPOJO Logger. This logger send log message to a log service if presents.
+ * iPOJO Logger.
+ * This class is an helper class implementing a simple log system. 
+ * This logger sends log messages to a log service if available.
  * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Logger {
     
     /**
-     * Ipojo default log level property.
+     * The iPOJO default log level property.
      */
     public static final String IPOJO_LOG_LEVEL = "ipojo.log.level";
 
     /**
-     * Log Level ERROR.
+     * The Log Level ERROR.
      */
     public static final int ERROR = 1;
 
     /**
-     * Log Level WARNING.
+     * The Log Level WARNING.
      */
     public static final int WARNING = 2;
 
     /**
-     * Log Level INFO.
+     * The Log Level INFO.
      */
     public static final int INFO = 3;
 
     /**
-     * Log Level DEBUG.
+     * The Log Level DEBUG.
      */
     public static final int DEBUG = 4;
 
     /**
-     * Bundle Context.
+     * The Bundle Context used to get the
+     * log service.
      */
     private BundleContext m_context;
 
     /**
-     * Name of the logger.
+     * The name of the logger.
      */
     private String m_name;
 
     /**
-     * trace level of this logger.
+     * The trace level of this logger.
      */
     private int m_level;
 
     /**
-     * Constructor.
-     * 
-     * @param context : bundle context
-     * @param name : name of the logger
-     * @param level : trace level
+     * Creates a logger.
+     * @param context the bundle context
+     * @param name the name of the logger
+     * @param level the trace level
      */
     public Logger(BundleContext context, String name, int level) {
         m_name = name;
@@ -83,20 +85,19 @@
     }
     
     /**
-     * Constructor.
-     * 
-     * @param context : bundle context
-     * @param name : name of the logger
+     * Create a logger.
+     * Uses the default logger level.
+     * @param context the bundle context
+     * @param name the name of the logger
      */
     public Logger(BundleContext context, String name) {
         this(context, name, getDefaultLevel(context));
     }
 
     /**
-     * Log a message.
-     * 
-     * @param level : level of the message
-     * @param msg : the message to log
+     * Logs a message.
+     * @param level the level of the message
+     * @param msg the the message to log
      */
     public void log(int level, String msg) {
         if (m_level >= level) {
@@ -105,11 +106,10 @@
     }
 
     /**
-     * Log a message with an exception.
-     * 
-     * @param level : level of the message
-     * @param msg : message to log
-     * @param exception : exception attached to the message
+     * Logs a message with an exception.
+     * @param level the level of the message
+     * @param msg the message to log
+     * @param exception the exception attached to the message
      */
     public void log(int level, String msg, Throwable exception) {
         if (m_level >= level) {
@@ -118,10 +118,9 @@
     }
     
     /**
-     * Internal log method.
-     * 
-     * @param level : level of the message.
-     * @param msg : message to log
+     * Internal log method. 
+     * @param level the level of the message.
+     * @param msg the message to log
      */
     private void dispatch(int level, String msg) {
         
@@ -173,10 +172,9 @@
 
     /**
      * Internal log method.
-     * 
-     * @param level : level of the message.
-     * @param msg : message to log
-     * @param exception : exception attached to the message
+     * @param level the level of the message.
+     * @param msg the message to log
+     * @param exception the exception attached to the message
      */
     private void dispatch(int level, String msg, Throwable exception) {
         
@@ -232,10 +230,11 @@
     }
     
     /**
-     * Get the default logger level.
-     * The property is searched inside the framework properties, the system properties,
-     * and in the manifest from the given bundle context. By default, set the level to WARNING. 
-     * @param context : bundle context.
+     * Gets the default logger level.
+     * The property is searched inside the framework properties, 
+     * the system properties, and in the manifest from the given 
+     * bundle context. By default, set the level to {@link Logger#WARNING}. 
+     * @param context the bundle context.
      * @return the default log level.
      */
     private static int getDefaultLevel(BundleContext context) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java
index a36bf40..81a4111 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Property.java
@@ -31,60 +31,62 @@
 import org.osgi.framework.BundleContext;
 
 /**
- * Property class managing a property.
- * This class allows storing property value and calling setter method too.
+ * Property class managing a managed value.
+ * This class managed the method invocation as well as field injection.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Property implements FieldInterceptor {
 
     /**
-     * Name of the property (filed name if not set).
+     * The name of the property (field name if not set).
+     * Cannot change once set.
      */
     private final String m_name;
 
     /**
-     * Field of the property.
+     * The field of the property.
      * Cannot change once set.
      */
     private final String m_field;
 
     /**
-     * Setter method of the property.
+     * The setter method of the property.
+     * Cannot change once set.
      */
     private final Callback m_method;
 
     /**
-     * Value of the property.
+     * The value of the property.
      */
     private Object m_value;
 
     /**
-     * Type of the property.
+     * The type of the property.
      */
     private final Class m_type;
 
     /**
-     * Handler object on to use the logger.
+     * The handler object to get the logger.
      */
     private final Handler m_handler;
     
     /**
-     * Instance Manager.
+     * The instance manager.
      */
     private final InstanceManager m_manager;
 
     /**
-     * Configurable Property Constructor. At least the method or the field need
-     * to be referenced.
-     * 
-     * @param name : name of the property (optional)
-     * @param field : name of the field
-     * @param method : method name
-     * @param value : initial value of the property (optional)
-     * @param type : the type of the property
-     * @param manager : instance manager
-     * @param handler : handler object which manage this property.
-     * @throws ConfigurationException : occurs when the property value cannot be set.
+     * Creates a property. 
+     * At least the method or the field need
+     * to be specified.
+     * @param name the name of the property (optional)
+     * @param field the name of the field
+     * @param method the method name
+     * @param value the initial value of the property (optional)
+     * @param type the the type of the property
+     * @param manager the instance manager
+     * @param handler the handler object which manage this property.
+     * @throws ConfigurationException if the property value cannot be set.
      */
     public Property(String name, String field, String method, String value, String type, InstanceManager manager, Handler handler) throws ConfigurationException {
         m_handler = handler;
@@ -115,9 +117,9 @@
     }
 
     /**
-     * The set type method computes and returns the property type according to the given type name.
-     * @param type : the type name
-     * @param context : bundle context (used to load classes)
+     * Computes and returns the property type according to the given type name.
+     * @param type the the type name
+     * @param context the bundle context (used to load classes)
      * @return the class of the given type
      * @throws ConfigurationException if an error occurs when loading the type class for non-primitive types.
      */
@@ -161,11 +163,11 @@
     }
 
     /**
-     * Get the Class object of a type array.
-     * @param type : the string descriptor of the type (must end by [] )
-     * @param context : bundle context (used to load classes)
+     * Gets the Class object of a type array.
+     * @param type the string descriptor of the type (must end by [] )
+     * @param context the bundle context (used to load classes)
      * @return the Class object of the given type array.
-     * @throws ConfigurationException : if the class cannot be loaded
+     * @throws ConfigurationException if the class cannot be loaded
      */
     private static Class computeArrayType(String type, BundleContext context) throws ConfigurationException {
         String internalType = type.substring(0, type.length() - 2);
@@ -220,7 +222,8 @@
     }
 
     /**
-     * Get method name, null if no method.
+     * Gets the method name, 
+     * <code>null</code> if no method.
      * @return the method name.
      */
     public String getMethod() {
@@ -229,16 +232,16 @@
     }
 
     /**
-     * Check if the property has a method callback.
-     * @return true if the property has a method.
+     * Checks if the property has a method callback.
+     * @return <code>true</code> if the property has a method.
      */
     public boolean hasMethod() {
         return m_method != null;
     }
 
     /**
-     * Check if the property has a field.
-     * @return true if the property has a field.
+     * Checks if the property has a field.
+     * @return <code>true</code> if the property has a field.
      */
     public boolean hasField() {
         return m_field != null;
@@ -249,8 +252,8 @@
     }
 
     /**
-     * Fix the value of the property.
-     * @param value : the new value.
+     * Sets the value of the property.
+     * @param value the new value.
      */
     public void setValue(Object value) {
         synchronized (this) {
@@ -275,10 +278,10 @@
     }
 
     /**
-     * Test if the given value is assignable to the given type.
-     * @param type : class of the type
-     * @param value : object to check
-     * @return true if the object is assignable in the property of type 'type'.
+     * Checks if the given value is assignable to the given type.
+     * @param type the class of the type
+     * @param value the object to check
+     * @return <code>true</code> if the object is assignable in the property of type 'type'.
      */
     public static boolean isAssignable(Class type, Object value) {
         if (value == null || type.isInstance(value)) { // When the value is null, the assign works necessary.
@@ -301,11 +304,11 @@
     }
 
     /**
-     * Create an object of the given type with the given String value.
-     * @param type : type of the returned object
-     * @param strValue : String value.
+     * Creates an object of the given type with the given String value.
+     * @param type the type of the returned object
+     * @param strValue the String value.
      * @return the object of type 'type' created from the String 'value'
-     * @throws ConfigurationException occurs when the object cannot be created.
+     * @throws ConfigurationException if the object cannot be created.
      */
     public static Object create(Class type, String strValue) throws ConfigurationException {
         if (Boolean.TYPE.equals(type)) { return new Boolean(strValue); }
@@ -343,11 +346,12 @@
     }
 
     /**
-     * Create an array object containing the type 'interntype' from the String array 'values'.
-     * @param interntype : internal type of the array.
-     * @param values : String array
+     * Creates an array object containing the type component type from 
+     * the String array 'values'.
+     * @param interntype the internal type of the array.
+     * @param values the String array
      * @return the array containing objects created from the 'values' array
-     * @throws ConfigurationException occurs when the array cannot be created correctly
+     * @throws ConfigurationException if the array cannot be created correctly
      */
     public static Object createArrayObject(Class interntype, String[] values) throws ConfigurationException {
         if (Boolean.TYPE.equals(interntype)) {
@@ -430,8 +434,9 @@
     }
 
     /**
-     * Invoke the setter method on the given pjo object. If no specified pojo object, will call on each created pojo object.
-     * @param instance : the created object (could be null
+     * Invokes the setter method on the given pojo object. 
+     * If no specified pojo object, it calls on each created pojo object.
+     * @param instance the created object (could be <code>null</code>)
      * @see org.apache.felix.ipojo.Handler#onCreation(java.lang.Object)
      */
     public synchronized void invoke(Object instance) {
@@ -455,9 +460,9 @@
 
     /**
      * A field value is required by the object 'pojo'.
-     * @param pojo : POJO object
-     * @param fieldName : field
-     * @param value : last value
+     * @param pojo the POJO object
+     * @param fieldName the field
+     * @param value the last value
      * @return the value if the handler want to inject this value.
      * @see org.apache.felix.ipojo.FieldInterceptor#onGet(java.lang.Object, java.lang.String, java.lang.Object)
      */
@@ -467,9 +472,9 @@
 
     /**
      * The field 'field' receives a new value.
-     * @param pojo : pojo
-     * @param fieldName : field name
-     * @param value : new value
+     * @param pojo the pojo
+     * @param fieldName the field name
+     * @param value the new value
      * @see org.apache.felix.ipojo.FieldInterceptor#onSet(java.lang.Object, java.lang.String, java.lang.Object)
      */
     public void onSet(Object pojo, String fieldName, Object value) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java
index c320f9d..0cc3bf2 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/ServiceReferenceRankingComparator.java
@@ -25,16 +25,18 @@
 
 /**
  * Service Reference Comparator.
- * This comparator follow OSGi Ranking policy.
+ * This comparator follows OSGi Ranking policy.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ServiceReferenceRankingComparator implements Comparator {
 
     /**
-     * Compare two service reference.
-     * @param ref1 : reference 1
-     * @param ref2 : reference 2
-     * @return -1 if the reference 1 is 'higher' than the reference 2, 1 otherwise. (higher is term of ranking means a lower index)
+     * Compares two service reference.
+     * @param ref1 the reference 1
+     * @param ref2 the reference 2
+     * @return <code>-1</code> if the reference 1 
+     * is 'higher' than the reference 2, <code>1</code> otherwise. 
+     * (higher is term of ranking means a lower index)
      * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object)
      */
     public int compare(Object ref1, Object ref2) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Tracker.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Tracker.java
index 9fe4925..a2cbe76 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Tracker.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/Tracker.java
@@ -41,55 +41,61 @@
 public class Tracker implements TrackerCustomizer {
 
     /**
-     * Bundle context against which this Tracker object is tracking.
+     * The bundle context against which this Tracker object is tracking.
      */
     protected BundleContext m_context;
 
     /**
-     * Filter specifying search criteria for the services to track.
+     * the filter specifying search criteria for the services to track.
      */
     protected Filter m_filter;
 
     /**
-     * TrackerCustomizer object for this tracker.
+     * The TrackerCustomizer object for this tracker.
      */
     protected TrackerCustomizer m_customizer;
 
     /**
-     * Filter string for use when adding the ServiceListener. If this field is set, then certain optimizations can be taken since we don't have a user supplied filter.
+     * The filter string for use when adding the ServiceListener.
+     * If this field is set, then certain optimizations can be taken since we don't have a user supplied filter.
      */
     protected String m_listenerFilter;
 
     /**
-     * Class name to be tracked. If this field is set, then we are tracking by class name.
+     * The class name to be tracked. If this field is set, then we are 
+     * tracking by class name.
      */
     private String m_trackClass;
 
     /**
-     * Reference to be tracked. If this field is set, then we are tracking a single ServiceReference.
+     * The reference to be tracked. If this field is set, then we are 
+     * tracking a single ServiceReference.
      */
     private ServiceReference m_trackReference;
 
     /**
-     * Tracked services: ServiceReference object -> customized. Object and ServiceListener object
+     * The tracked services: ServiceReference object -> customized. 
+     *Object and ServiceListener object
      */
     private Tracked m_tracked;
 
     /**
-     * Cached ServiceReference for getServiceReference. This field is volatile since it is accessed by multiple threads.
+     * The cached ServiceReference for getServiceReference. 
+     * This field is volatile since it is accessed by multiple threads.
      */
     private volatile ServiceReference m_cachedReference;
 
     /**
-     * Cached service object for getService. This field is volatile since it is accessed by multiple threads.
+     * The cached service object for getService. This field is volatile 
+     * since it is accessed by multiple threads.
      */
     private volatile Object m_cachedService;
 
     /**
-     * Create a Tracker object on the specified ServiceReference object.
+     * Creates a Tracker object on the specified ServiceReference object.
      * The service referenced by the specified ServiceReference object will be tracked by this Tracker.
-     * @param context BundleContext object against which the tracking is done.
-     * @param reference ServiceReference object for the service to be tracked.
+     * @param context The BundleContext object against which the tracking is done.
+     * @param reference The ServiceReference object for the service to be tracked.
      * @param customizer The customizer object to call when services are added, modified, or removed in this Tracker object. If customizer is null, then this Tracker object will be used as
      *            the TrackerCustomizer object and the Tracker object will call the TrackerCustomizer methods on itself.
      */
@@ -111,11 +117,11 @@
     }
 
     /**
-     * Create a Tracker object on the specified class name.
+     * Creates a Tracker object on the specified class name.
      * Services registered under the specified class name will be tracked by this Tracker object.
-     * @param context BundleContext object against which the tracking is done.
-     * @param clazz Class name of the services to be tracked.
-     * @param customizer The customizer object to call when services are added, modified, or removed in this Tracker object. If customizer is null, then this Tracker object will be used as
+     * @param context the BundleContext object against which the tracking is done.
+     * @param clazz the Class name of the services to be tracked.
+     * @param customizer the customizer object to call when services are added, modified, or removed in this Tracker object. If customizer is null, then this Tracker object will be used as
      *            the TrackerCustomizer object and the Tracker object will call the TrackerCustomizer methods on itself.    
      */
     public Tracker(BundleContext context, String clazz, TrackerCustomizer customizer) {
@@ -138,11 +144,11 @@
     }
 
     /**
-     * Create a Tracker object on the specified Filter object.
+     * Creates a Tracker object on the specified Filter object.
      * <p>
      * Services which match the specified Filter object will be tracked by this Tracker object.
-     * @param context BundleContext object against which the tracking is done.
-     * @param filter Filter object to select the services to be tracked.
+     * @param context the BundleContext object against which the tracking is done.
+     * @param filter the Filter object to select the services to be tracked.
      * @param customizer The customizer object to call when services are added, modified, or removed in this Tracker object. If customizer is null, then this Tracker object will be used as the
      *            TrackerCustomizer object and the Tracker object will call the TrackerCustomizer methods on itself.   
      */
@@ -163,7 +169,7 @@
     }
 
     /**
-     * Open this Tracker object and begin tracking services.
+     * Opens this Tracker object and begin tracking services.
      * <p>
      * Services which match the search criteria specified when this Tracker object was created are now tracked by this Tracker object.
      */
@@ -208,7 +214,7 @@
     }
 
     /**
-     * Close this Tracker object.
+     * Closes this Tracker object.
      * <p>
      * This method should be called when this Tracker object should end the tracking of services.
      */
@@ -240,7 +246,7 @@
      * on the BundleContext object with which this Tracker object was created, passing the specified ServiceReference object.
      * <p>
      * This method can be overridden in a subclass to customize the service object to be tracked for the service being added. In that case, take care not to rely on the default implementation of removedService that will unget the service.
-     * @param reference Reference to service being added to this Tracker object.
+     * @param reference the Reference to service being added to this Tracker object.
      * @return The service object to be tracked for the service added to this Tracker object.
      * @see TrackerCustomizer
      */
@@ -250,7 +256,7 @@
 
     /**
      * Default implementation of the TrackerCustomizer.addedService method.  
-     * @param reference added reference.
+     * @param reference the added reference.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#addedService(org.osgi.framework.ServiceReference)
      */
     public void addedService(ServiceReference reference) {
@@ -261,7 +267,7 @@
      * Default implementation of the TrackerCustomizer.modifiedService method.
      * <p>
      * This method is only called when this Tracker object has been constructed with a null TrackerCustomizer argument. The default implementation does nothing.
-     * @param reference Reference to modified service.
+     * @param reference the Reference to modified service.
      * @param service The service object for the modified service.
      * @see TrackerCustomizer
      */
@@ -276,7 +282,7 @@
      * BundleContext object with which this Tracker object was created, passing the specified ServiceReference object.
      * <p>
      * This method can be overridden in a subclass. If the default implementation of addingService method was used, this method must unget the service.
-     * @param reference Reference to removed service.
+     * @param reference the Reference to removed service.
      * @param service The service object for the removed service.
      * @see TrackerCustomizer
      */
@@ -285,10 +291,10 @@
     }
 
     /**
-     * Wait for at least one service to be tracked by this Tracker object.
+     * Waits for at least one service to be tracked by this Tracker object.
      * <p>
      * It is strongly recommended that waitForService is not used during the calling of the BundleActivator methods. BundleActivator methods are expected to complete in a short period of time.
-     * @param timeout time interval in milliseconds to wait. If zero, the method will wait indefinately.
+     * @param timeout the time interval in milliseconds to wait. If zero, the method will wait indefinately.
      * @return Returns the result of getService().
      * @throws InterruptedException If another thread has interrupted the current thread.
      */
@@ -312,8 +318,8 @@
     }
 
     /**
-     * Return an array of ServiceReference objects for all services being tracked by this Tracker object.
-     * @return Array of ServiceReference objects or null if no service are being tracked.
+     * Returns an array of ServiceReference objects for all services being tracked by this Tracker object.
+     * @return Array of ServiceReference objects or <code>null</code> if no service are being tracked.
      */
     public ServiceReference[] getServiceReferences() {
         Tracked tracked = this.m_tracked; // use local var since we are not synchronized
@@ -333,7 +339,7 @@
     }
 
     /**
-     * Get the list of stored service reference.
+     * Gets the list of stored service reference.
      * @return the list containing used service reference
      */
     public List/*<ServiceReference>*/getServiceReferencesList() {
@@ -355,10 +361,10 @@
     }
     
     /**
-     * Return the list of references used by the tracker.
+     * Returns the list of references used by the tracker.
      * A reference becomes used when the dependency has already
-     * call getService on this reference.
-     * @return : the list of used references.
+     * called getService on this reference.
+     * @return the list of used references.
      */
     public List/*<ServiceReference>*/getUsedServiceReferences() {
         Tracked tracked = this.m_tracked; // use local var since we are not synchronized
@@ -402,8 +408,8 @@
 
     /**
      * Returns the service object for the specified ServiceReference object if the referenced service is being tracked by this Tracker object.
-     * @param reference Reference to the desired service.
-     * @return Service object or null if the service referenced by the specified ServiceReference object is not being tracked.
+     * @param reference the Reference to the desired service.
+     * @return the Service object or <code>null</code> if the service referenced by the specified ServiceReference object is not being tracked.
      */
     public Object getService(ServiceReference reference) {
         Tracked tracked = this.m_tracked; // use local var since we are not synchronized
@@ -428,8 +434,8 @@
     }
 
     /**
-     * Unget the given service reference.
-     * @param reference : service reference to unget.
+     * Ungets the given service reference.
+     * @param reference the service reference to unget.
      */
     public void ungetService(ServiceReference reference) {
         Tracked tracked = this.m_tracked; // use local var since we are not synchronized
@@ -446,8 +452,8 @@
     }
 
     /**
-     * Return an array of service objects for all services being tracked by this Tracker object.
-     * @return Array of service objects or null if no service are being tracked.
+     * Returns an array of service objects for all services being tracked by this Tracker object.
+     * @return Array of service objects or <code>null</code> if no service are being tracked.
      */
     public Object[] getServices() {
         Tracked tracked = this.m_tracked; // use local var since we are not synchronized
@@ -474,7 +480,7 @@
      * Returns a service object for one of the services being tracked by this Tracker object.
      * <p>
      * If any services are being tracked, this method returns the result of calling getService(getServiceReference()).
-     * @return Service object or null if no service is being tracked.
+     * @return Service object or <code>null</code> if no service is being tracked.
      */
     public Object getService() {
         Object service = m_cachedService;
@@ -485,9 +491,9 @@
     }
 
     /**
-     * Remove a service from this Tracker object. The specified service will be removed from this Tracker object. If the specified service was being tracked then the
+     * Removes a service from this Tracker object. The specified service will be removed from this Tracker object. If the specified service was being tracked then the
      * TrackerCustomizer.removedService method will be called for that service.
-     * @param reference Reference to the service to be removed.
+     * @param reference the Reference to the service to be removed.
      */
     public void remove(ServiceReference reference) {
         Tracked tracked = this.m_tracked; // use local var since we are not synchronized
@@ -498,8 +504,8 @@
     }
 
     /**
-     * Return the number of services being tracked by this Tracker object.
-     * @return Number of services being tracked.
+     * Returns the number of services being tracked by this Tracker object.
+     * @return the Number of services being tracked.
      */
     public int size() {
         Tracked tracked = this.m_tracked; //use local var since we are not synchronized
@@ -521,19 +527,19 @@
         static final long serialVersionUID = -7420065199791006079L;
 
         /**
-         * List of ServiceReferences in the process of being added. This is used to deal with nesting of ServiceEvents. Since ServiceEvents are synchronously delivered, ServiceEvents can be nested. For example, when processing the adding of a service
+         * The list of ServiceReferences in the process of being added. This is used to deal with nesting of ServiceEvents. Since ServiceEvents are synchronously delivered, ServiceEvents can be nested. For example, when processing the adding of a service
          * and the customizer causes the service to be unregistered, notification to the nested call to untrack that the service was unregistered can be made to the track method. Since the ArrayList implementation is not synchronized, all access to
          * this list must be protected by the same synchronized object for thread safety.
          */
         private List m_adding;
 
         /**
-         * true if the tracked object is closed. This field is volatile because it is set by one thread and read by another.
+         * <code>true</code> if the tracked object is closed. This field is volatile because it is set by one thread and read by another.
          */
         private volatile boolean m_closed;
 
         /**
-         * Initial list of ServiceReferences for the tracker. This is used to correctly process the initial services which could become unregistered before they are tracked. This is necessary since the initial set of tracked services are not
+         * The Initial list of ServiceReferences for the tracker. This is used to correctly process the initial services which could become unregistered before they are tracked. This is necessary since the initial set of tracked services are not
          * "announced" by ServiceEvents and therefore the ServiceEvent for unregistration could be delivered before we track the service. A service must not be in both the initial and adding lists at the same time. A service must be moved from the
          * initial list to the adding list "atomically" before we begin tracking it. Since the LinkedList implementation is not synchronized, all access to this list must be protected by the same synchronized object for thread safety.
          */
@@ -550,7 +556,7 @@
         }
 
         /**
-         * Set initial list of services into tracker before ServiceEvents begin to be received. This method must be called from Tracker.open while synchronized on this object in the same synchronized block as the addServiceListener call.
+         * Sets initial list of services into tracker before ServiceEvents begin to be received. This method must be called from Tracker.open while synchronized on this object in the same synchronized block as the addServiceListener call.
          * @param references The initial list of services to be tracked.
          */
         protected void setInitialServices(ServiceReference[] references) {
@@ -562,7 +568,7 @@
         }
 
         /**
-         * Track the initial list of services. This is called after ServiceEvents can begin to be received. This method must be called from Tracker.open while not synchronized on this object after the addServiceListener call.
+         * Tracks the initial list of services. This is called after ServiceEvents can begin to be received. This method must be called from Tracker.open while not synchronized on this object after the addServiceListener call.
          */
         protected void trackInitialServices() {
             while (true) {
@@ -597,7 +603,7 @@
 
         /**
          * ServiceListener method for the Tracker class. This method must NOT be synchronized to avoid deadlock potential.
-         * @param event ServiceEvent object from the framework.
+         * @param event the ServiceEvent object from the framework.
          */
         public void serviceChanged(ServiceEvent event) {
             //Check if we had a delayed call (which could happen when we close).
@@ -633,8 +639,8 @@
         }
 
         /**
-         * Begin to track the referenced service.
-         * @param reference Reference to a service to be tracked.
+         * Begins to track the referenced service.
+         * @param reference the Reference to a service to be tracked.
          */
         protected void track(ServiceReference reference) {
             Object object;
@@ -665,7 +671,7 @@
 
         /**
          * Common logic to add a service to the tracker used by track and trackInitialServices. The specified reference must have been placed in the adding list before calling this method.
-         * @param reference Reference to a service to be tracked.
+         * @param reference the Reference to a service to be tracked.
          */
         private void trackAdding(ServiceReference reference) {
             boolean mustBeTracked = false;
@@ -704,8 +710,8 @@
         }
 
         /**
-         * Discontinue tracking the referenced service.
-         * @param reference Reference to the tracked service.
+         * Discontinues tracking the referenced service.
+         * @param reference the Reference to the tracked service.
          */
         protected void untrack(ServiceReference reference) {
             Object object;
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/TrackerCustomizer.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/TrackerCustomizer.java
index 3312d85..69693cf 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/util/TrackerCustomizer.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/util/TrackerCustomizer.java
@@ -30,7 +30,7 @@
      * A service is being added to the Tracker object.
      * This method is called before a service which matched the search parameters of the Tracker object is added to it. This method should return the service object to be tracked for this ServiceReference object.
      * The returned service object is stored in the Tracker object and is available from the getService and getServices methods.
-     * @param reference Reference to service being added to the Tracker object.
+     * @param reference the Reference to service being added to the Tracker object.
      * @return The service object to be tracked for the ServiceReference object or null if the ServiceReference object should not be tracked.
      */
     boolean addingService(ServiceReference reference);
@@ -45,7 +45,7 @@
     /**
      * A service tracked by the Tracker object has been modified.
      * This method is called when a service being tracked by the Tracker object has had it properties modified.
-     * @param reference Reference to service that has been modified.
+     * @param reference the Reference to service that has been modified.
      * @param service The service object for the modified service.
      */
     void modifiedService(ServiceReference reference, Object service);
@@ -53,7 +53,7 @@
     /**
      * A service tracked by the Tracker object has been removed.
      * This method is called after a service is no longer being tracked by the Tracker object.
-     * @param reference Reference to service that has been removed.
+     * @param reference the Reference to service that has been removed.
      * @param service The service object for the removed service.
      */
     void removedService(ServiceReference reference, Object service);
diff --git a/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Attribute.java b/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Attribute.java
index 5ffba50..6910068 100644
--- a/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Attribute.java
+++ b/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Attribute.java
@@ -19,31 +19,31 @@
 package org.apache.felix.ipojo.metadata;
 
 /**
- * Attribute.
- * 
+ * An attribute is a key-value pair. It represents the attribute
+ * of XML elements.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Attribute {
 
     /**
-     * Name of the attribute.
+     * The name of the attribute.
      */
     private String m_name;
 
     /**
-     * Value of the attribute.
+     * The value of the attribute.
      */
     private String m_value;
 
     /**
-     * Namespace of the attribute.
+     * The namespace of the attribute.
      */
     private String m_nameSpace;
 
     /**
-     * Constructor.
-     * @param name : name of the attribute.
-     * @param value : value of the attribute.
+     * Creates an attribute.
+     * @param name the name of the attribute.
+     * @param value the value of the attribute.
      */
     public Attribute(String name, String value) {
         m_name = name.toLowerCase();
@@ -51,10 +51,10 @@
     }
 
     /**
-     * Constructor.
-     * @param name : name of the attribute.
-     * @param value : value of the attribute.
-     * @param ns : namespace of the attribute.
+     * Creates an attribute.
+     * @param name the name of the attribute.
+     * @param value the value of the attribute.
+     * @param ns the namespace of the attribute.
      */
     public Attribute(String name, String ns, String value) {
         m_name = name.toLowerCase();
@@ -65,7 +65,7 @@
     }
 
     /**
-     * Get the attribute name.
+     * Gets the attribute name.
      * @return the name
      */
     public String getName() {
@@ -73,7 +73,7 @@
     }
 
     /**
-     * Get attribute value.
+     * Gets attribute value.
      * @return the value
      */
     public String getValue() {
@@ -81,7 +81,7 @@
     }
 
     /**
-     * Get attribute namespace.
+     * Gets attribute namespace.
      * @return the namespace
      */
     public String getNameSpace() {
diff --git a/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Element.java b/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Element.java
index f984aa8..8a357f3 100644
--- a/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Element.java
+++ b/ipojo/metadata/src/main/java/org/apache/felix/ipojo/metadata/Element.java
@@ -27,40 +27,41 @@
 import java.util.Set;
 
 /**
- * Element.
- * 
+ * An element represents an XML Element.
+ * It contains a name, a namepace, {@link Attribute} objects
+ * and sub-elements. This class is used to parse iPOJO metadata.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class Element {
 
     /**
-     * Name of the element.
+     * The name of the element.
      */
     private String m_name;
 
     /**
-     * Name space of the element.
+     * The namespace of the element.
      */
     private String m_nameSpace;
 
     /**
-     * Map of attributes of the element.
-     * The map key is the qualified name of the attribute (ns:name)
+     * The map of attributes of the element (attribute name -> {@link Attribute}).
+     * The map key is the qualified name of the attribute (<code>ns:name</code>)
      * The value is the attribute object.
      */
     private Map m_attributes = new HashMap();
 
     /**
-     * Map of the sub-element of the element.
+     * The map of the sub-element of the element (element name -> {@link Element}.
      * The map key is the element qualified name (ns:name).
      * The value is the array of element of this name.
      */
     private Map m_elements = new HashMap();
 
     /**
-     * Constructor.
-     * @param name : the name of the element
-     * @param ns : the namespace of the element
+     * Creates an Element.
+     * @param name the name of the element
+     * @param ns the namespace of the element
      */
     public Element(String name, String ns) {
         m_name = name.toLowerCase();
@@ -70,7 +71,8 @@
     }
 
     /**
-     * Get sub-elements.
+     * Gets sub-elements.
+     * If no sub-elements, an empty array is returned.
      * @return the sub elements
      */
     public Element[] getElements() {
@@ -87,7 +89,8 @@
     }
 
     /**
-     * Get element attributes.
+     * Gets element attributes.
+     * If no attributes, an empty array is returned.
      * @return the attributes
      */
     public Attribute[] getAttributes() {
@@ -95,7 +98,7 @@
     }
 
     /**
-     * Get element name.
+     * Gets element name.
      * @return the name of the element
      */
     public String getName() {
@@ -103,7 +106,7 @@
     }
 
     /**
-     * Get element namespace.
+     * Gets element namespace.
      * @return the namespace of the element
      */
     public String getNameSpace() {
@@ -111,9 +114,10 @@
     }
 
     /**
-     * Return the value of the attribute given in parameter.
-     * @param name : the name of the searched attribute
-     * @return the value of the attribute given in parameter, null if the attribute does not exist
+     * Returns the value of the attribute given in parameter.
+     * @param name the name of the searched attribute
+     * @return the value of the attribute given in parameter,
+     * <code>null</code> if the attribute does not exist
      */
     public String getAttribute(String name) {
         name = name.toLowerCase();
@@ -126,10 +130,11 @@
     }
 
     /**
-     * Return the value of the attribute "name" of the namespace "ns".
-     * @param name : name of the attribute to find
-     * @param ns : namespace of the attribute to find
-     * @return the String value of the attribute, or null if the attribute is not found.
+     * Returns the value of the attribute "name" of the namespace "ns".
+     * @param name the name of the attribute to find
+     * @param ns the namespace of the attribute to find
+     * @return the String value of the attribute, or 
+     * <code>null</code> if the attribute is not found.
      */
     public String getAttribute(String name, String ns) {
         name = ns.toLowerCase() + ":" + name.toLowerCase();
@@ -137,7 +142,7 @@
     }
     
     /**
-     * Get the qualified name of the current element.
+     * Gets the qualified name of the current element.
      * @return the qualified name of the current element.
      */
     private String getQualifiedName() {
@@ -149,8 +154,8 @@
     }
 
     /**
-     * Add a sub-element.
-     * @param elem : the element to add
+     * Adds a sub-element.
+     * @param elem the element to add
      */
     public void addElement(Element elem) {
         Element[] array = (Element[]) m_elements.get(elem.getQualifiedName());
@@ -165,8 +170,8 @@
     }
 
     /**
-     * Remove a sub-element.
-     * @param elem : the element to remove
+     * Removes a sub-element.
+     * @param elem the element to remove
      */
     public void removeElement(Element elem) {
         Element[] array = (Element[]) m_elements.get(elem.getQualifiedName());
@@ -197,8 +202,8 @@
     }
 
     /**
-     * Add a attribute.
-     * @param att : the attribute to add
+     * Adds a attribute.
+     * @param att the attribute to add
      */
     public void addAttribute(Attribute att) {
         String name = att.getName().toLowerCase();
@@ -209,8 +214,8 @@
     }
 
     /**
-     * Remove an attribute.
-     * @param att : the attribute to remove
+     * Removes an attribute.
+     * @param att the attribute to remove
      */
     public void removeAttribute(Attribute att) {
         String name = att.getName();
@@ -221,9 +226,10 @@
     }
 
     /**
-     * Get the elements array of the element type given in parameter. This method look for an empty namespace.
-     * @param name : the type of the element to find (element name)
-     * @return the resulting element array (null if the search failed)
+     * Gets the elements array of the element type given in parameter. 
+     * This method look for an empty namespace.
+     * @param name the type of the element to find (element name)
+     * @return the resulting element array (<code>null</code> if the search failed)
      */
     public Element[] getElements(String name) {
         Element[] elems = (Element[]) m_elements.get(name.toLowerCase());
@@ -231,10 +237,10 @@
     }
 
     /**
-     * Get the elements array of the element type given in parameter.
-     * @param name : the type of the element to find (element name)
-     * @param ns : the namespace of the element
-     * @return the resulting element array (null if the search failed)
+     * Gets the elements array of the element type given in parameter.
+     * @param name the type of the element to find (element name)
+     * @param ns the namespace of the element
+     * @return the resulting element array (<code>null</code> if the search failed)
      */
     public Element[] getElements(String name, String ns) {
         if (ns == null || ns.length() == 0) {
@@ -245,19 +251,19 @@
     }
 
     /**
-     * Is the element contains a sub-element of the type given in parameter.
-     * @param name : type of the element to check.
-     * @return true if the element contains an element of the type "name"
+     * Does the element contain a sub-element of the type given in parameter.
+     * @param name the type of the element to check.
+     * @return <code>true</code> if the element contains an element of the type "name"
      */
     public boolean containsElement(String name) {
         return m_elements.containsKey(name.toLowerCase());
     }
 
     /**
-     * Is the element contains a sub-element of the type given in parameter. 
-     * @param name : type of the element to check.
-     * @param ns : the namespace of the element to check.
-     * @return true if the element contains an element of the type "name"
+     * Does the element contain a sub-element of the type given in parameter. 
+     * @param name the type of the element to check.
+     * @param ns the namespace of the element to check.
+     * @return <code>true</code> if the element contains an element of the type "name"
      */
     public boolean containsElement(String name, String ns) {
         if (ns != null && ns.length() != 0) {
@@ -267,16 +273,16 @@
     }
 
     /**
-     * Is the element contains an attribute of the name given in parameter.
-     * @param name : name of the element
-     * @return true if the element contains an attribute of the type "name"
+     * Does the element contain an attribute of the name given in parameter.
+     * @param name the name of the element
+     * @return <code>true</code> if the element contains an attribute of the type "name"
      */
     public boolean containsAttribute(String name) {
         return m_attributes.containsKey(name.toLowerCase());
     }
     
     /**
-     * Get the XML form of this element.
+     * Gets the XML form of this element.
      * @return the XML snippet representing this element.
      */
     public String toXMLString() {
@@ -285,7 +291,7 @@
 
     /**
      * Internal method to get XML form of an element.
-     * @param indent : indentation to used.
+     * @param indent the indentation to used.
      * @return the XML snippet representing this element.
      */
     private String toXMLString(int indent) {
@@ -343,8 +349,8 @@
 
     /**
      * Internal method to compute the toString method.
-     * @param indent : indentation to use.
-     * @return : the String form of this element.
+     * @param indent the indentation to use.
+     * @return the String form of this element.
      */
     private String toString(int indent) {
         String xml = "";