diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java
index a353bc3..a9d1319 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentFactory.java
@@ -40,51 +40,54 @@
 
 /**
  * The component factory manages component instance objects. This management
- * consist in creating and managing component instance build with the component
- * factory. This class could export Factory and ManagedServiceFactory services.
- * 
+ * consists to create and manage component instances build with the current 
+ * component factory. This class could export Factory and ManagedServiceFactory
+ * services.
+ * @see IPojoFactory
+ * @see TrackerCustomizer
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ComponentFactory extends IPojoFactory implements TrackerCustomizer {
 
     /**
-     * Tracker used to track required handler factories.
+     * The tracker used to track required handler factories.
      * Immutable once set.
      */
     protected Tracker m_tracker;
 
     /**
-     * Class loader to delegate loading.
+     * The class loader to delegate classloading.
      * Immutable once set.
      */
     private FactoryClassloader m_classLoader;
 
     /**
-     * Component Implementation class.
+     * The component implementation class.
+     * (manipulated byte array)
      */
     private byte[] m_clazz;
 
     /**
-     * Component Implementation Class Name.
+     * The component implementation qualified class name.
      * Immutable once set.
-     * This attribute is set during the construction of the factory.
+     * This attribute is set during the creation of the factory.
      */
     private String m_classname;
 
     /**
-     * Manipulation Metadata of the internal POJO.
+     * The manipulation metadata of the implementation class.
      * Immutable once set.
-     * This attribute is set during the construction of the factory.
+     * This attribute is set during the creation of the factory.
      */
     private PojoMetadata m_manipulation;
 
     /**
-     * Create a instance manager factory. The class is given in parameter. The
-     * component type is not a composite.
-     * @param context : bundle context
-     * @param clazz : the component class
-     * @param element : metadata of the component
-     * @throws ConfigurationException occurs when the element describing the factory is malformed.
+     * Creates a instance manager factory.
+     * The class is given in parameter. The component type is not a composite.
+     * @param context the bundle context
+     * @param clazz the component class
+     * @param element the metadata of the component
+     * @throws ConfigurationException if the element describing the factory is malformed.
      */
     public ComponentFactory(BundleContext context, byte[] clazz, Element element) throws ConfigurationException {
         this(context, element);
@@ -93,25 +96,30 @@
 
     /**
      * Create a instance manager factory.
-     * @param context : bundle context
-     * @param element : metadata of the component to create
-     * @throws ConfigurationException occurs when the element describing the factory is malformed.
+     * @param context the bundle context
+     * @param element the metadata of the component to create
+     * @throws ConfigurationException if element describing the factory is malformed.
      */
     public ComponentFactory(BundleContext context, Element element) throws ConfigurationException {
         super(context, element);
         check(element); // NOPMD. This invocation is normal.
     }
 
+    /**
+     * Gets the component type description of the current factory.
+     * @return the description of the component type attached to this factory.
+     * @see org.apache.felix.ipojo.IPojoFactory#getComponentTypeDescription()
+     */
     public ComponentTypeDescription getComponentTypeDescription() {
         return new PrimitiveTypeDescription(this);
     }
 
     /**
-     * Check method : allows a factory to check if given element is well-formed.
-     * A component factory metadata are correct if they contain the 'classname' attribute.
-     * As this method is called from the (single-thread) constructor, no synchronization is needed.
-     * @param element : the metadata
-     * @throws ConfigurationException occurs when the element describing the factory is malformed.
+     * Allows a factory to check if the given element is well-formed.
+     * A component factory metadata is correct if they contain the 'classname' attribute.
+     * As this method is called from the (single-threaded) constructor, no synchronization is needed.
+     * @param element the metadata describing the component
+     * @throws ConfigurationException if the element describing the factory is malformed.
      */
     public void check(Element element) throws ConfigurationException {
         m_classname = element.getAttribute("classname");
@@ -132,11 +140,11 @@
     /**
      * Creates a primitive instance.
      * This method is called when holding the lock.
-     * @param config : instance configuration
-     * @param context : service context.
-     * @param handlers : handler to use
+     * @param config the instance configuration
+     * @param context the service context (null if the instance has to be created in the global space).
+     * @param handlers the handlers to attach to the instance
      * @return the created instance
-     * @throws org.apache.felix.ipojo.ConfigurationException : if the configuration process failed.
+     * @throws org.apache.felix.ipojo.ConfigurationException if the configuration process failed.
      * @see org.apache.felix.ipojo.IPojoFactory#createInstance(java.util.Dictionary, org.apache.felix.ipojo.IPojoContext, org.apache.felix.ipojo.HandlerManager[])
      */
     public ComponentInstance createInstance(Dictionary config, IPojoContext context, HandlerManager[] handlers) throws org.apache.felix.ipojo.ConfigurationException {
@@ -167,10 +175,13 @@
 
     /**
      * Defines a class.
-     * This method need to be synchronized to avoid that the classloader is created twice.
-     * @param name : qualified name of the class
-     * @param clazz : byte array of the class
-     * @param domain : protection domain of the class
+     * This method needs to be synchronized to avoid that the classloader 
+     * is created twice.
+     * This method delegate the <code>define</code> method invocation to the
+     * factory classloader.
+     * @param name the qualified name of the class
+     * @param clazz the byte array of the class
+     * @param domain the protection domain of the class
      * @return the defined class object
      */
     public synchronized Class defineClass(String name, byte[] clazz, ProtectionDomain domain) {
@@ -182,20 +193,25 @@
 
     /**
      * Returns the URL of a resource.
-     * @param resName : resource name
+     * This methods delegates the invocation to the 
+     * {@link Bundle#getResource(String)} method.
+     * @param resName the resource name
      * @return the URL of the resource
      */
     public URL getResource(String resName) {
-        //No synchronization needed, the context is immutable and the call is managed by the underlying framework.
+        //No synchronization needed, the context is immutable and
+        //the call is managed by the underlying framework.
         return m_context.getBundle().getResource(resName);
     }
 
     /**
-     * Loads a class.
-     * @param className : name of the class to load
+     * Loads a class. This method checks if the class
+     * to load is the implementation class or not.
+     * If it is, the factory classloader is used, else
+     * the {@link Bundle#loadClass(String)} is called.
+     * @param className the name of the class to load
      * @return the resulting Class object
-     * @throws ClassNotFoundException 
-     * @throws ClassNotFoundException : happen when the class is not found
+     * @throws ClassNotFoundException if the class is not found
      */
     public Class loadClass(String className) throws ClassNotFoundException {
         if (m_clazz != null && m_classname.equals(className)) {  // Immutable fields.
@@ -206,7 +222,7 @@
 
     /**
      * Starts the factory.
-     * This method is called with the lock.
+     * This method is called when holding the monitor lock.
      */
     public void starting() {
         if (m_tracker != null) {
@@ -227,7 +243,7 @@
 
     /**
      * Stops all the instance managers.
-     * This method is called with the lock.
+     * This method is called when holding the lock.
      */
     public void stopping() {
         if (m_tracker != null) {
@@ -237,8 +253,10 @@
     }
 
     /**
-     * Computes the factory name.
-     * This method does not manipulate any non-immutable fields, so does not need to be synchronized. 
+     * Computes the factory name. The factory name is computed from
+     * the 'name' and 'classname' attributes.
+     * This method does not manipulate any non-immutable fields,
+     * so does not need to be synchronized. 
      * @return the factory name.
      */
     public String getFactoryName() {
@@ -252,7 +270,8 @@
 
     /**
      * Computes required handlers.
-     * This method does not manipulate any non-immutable fields, so does not need to be synchronized.
+     * This method does not manipulate any non-immutable fields, 
+     * so does not need to be synchronized.
      * @return the required handler list.
      */
     public List getRequiredHandlerList() {
@@ -302,11 +321,12 @@
     }
 
     /**
-     * A new handler factory is detected.
+     * This method is called when a new handler factory is detected.
      * Test if the factory can be used or not.
-     * This method need to be synchronized as it accesses to the content of required handlers.
-     * @param reference : the new service reference.
-     * @return true if the given factory reference match with a required handler.
+     * This method need to be synchronized as it accesses to the content 
+     * of required handlers.
+     * @param reference the new service reference.
+     * @return <code>true</code> if the given factory reference matches with a required handler.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#addingService(org.osgi.framework.ServiceReference)
      */
     public synchronized boolean addingService(ServiceReference reference) {        
@@ -327,9 +347,10 @@
     }
 
     /**
-     * A matching service has been added to the tracker, we can no compute the factory state. This method is synchronized to avoid concurrent calls to
-     * method modifying the factory state.
-     * @param reference : added reference.
+     * This method is called when a matching service has been added to the tracker, 
+     * we can no compute the factory state. This method is synchronized to avoid 
+     * concurrent calls to method modifying the factory state.
+     * @param reference the added service reference.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#addedService(org.osgi.framework.ServiceReference)
      */
     public synchronized void addedService(ServiceReference reference) {
@@ -339,10 +360,11 @@
     }
 
     /**
-     * A used factory disappears.
-     * This method is synchronized to avoid concurrent calls to method modifying the factory state.
-     * @param reference : service reference.
-     * @param service : factory object.
+     * This method is called when a used handler factory disappears.
+     * This method is synchronized to avoid concurrent calls to method modifying 
+     * the factory state.
+     * @param reference the leaving service reference.
+     * @param service  the handler factory object.
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#removedService(org.osgi.framework.ServiceReference, java.lang.Object)
      */
     public synchronized void removedService(ServiceReference reference, Object service) {
@@ -358,9 +380,11 @@
     }
 
     /**
-     * A used handler factory is modified.
-     * @param reference : the service reference
-     * @param service : the Factory object (if already get)
+     * This method is called when a used handler factory is modified.
+     * However, handler factory modification is not possible, so this method
+     * is never called.
+     * @param reference the service reference
+     * @param service the Factory object (if already get)
      * @see org.apache.felix.ipojo.util.TrackerCustomizer#modifiedService(org.osgi.framework.ServiceReference, java.lang.Object)
      */
     public void modifiedService(ServiceReference reference, Object service) {
@@ -376,21 +400,25 @@
     }
 
     /**
-     * FactoryClassloader.
+     * this class defines the classloader attached to a factory.
+     * This class loader is used to load the implementation (e.g. manipulated)
+     * class.
+     * @see ClassLoader
+     * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
      */
     private class FactoryClassloader extends ClassLoader {
 
         /**
-         * Map of defined classes [Name, Class Object].
+         * The map of defined classes [Name, Class Object].
          */
         private final Map m_definedClasses = new HashMap();
 
         /**
          * The defineClass method.
-         * @param name : name of the class
-         * @param clazz : the byte array of the class
-         * @param domain : the protection domain
-         * @return : the defined class.
+         * @param name name of the class
+         * @param clazz the byte array of the class
+         * @param domain the protection domain
+         * @return the defined class.
          */
         public Class defineClass(String name, byte[] clazz, ProtectionDomain domain) {
             if (m_definedClasses.containsKey(name)) { return (Class) m_definedClasses.get(name); }
@@ -400,8 +428,8 @@
         }
 
         /**
-         * Return the URL of the asked resource.
-         * @param arg : the name of the resource to find.
+         * Returns the URL of the required resource.
+         * @param arg the name of the resource to find.
          * @return the URL of the resource.
          * @see java.lang.ClassLoader#getResource(java.lang.String)
          */
@@ -410,31 +438,38 @@
         }
 
         /**
-         * Load the class.
+         * Loads the given class.
          * @see java.lang.ClassLoader#loadClass(java.lang.String, boolean)
-         * @param name : the name of the class
-         * @param resolve : should be the class resolve now ?
-         * @return : the loaded class
-         * @throws ClassNotFoundException : the class to load is not found
+         * @param name the name of the class
+         * @param resolve should be the class resolve now ?
+         * @return the loaded class object
+         * @throws ClassNotFoundException if the class to load is not found
+         * @see java.lang.ClassLoader#loadClass(String, boolean)
          */
         protected synchronized Class loadClass(String name, boolean resolve) throws ClassNotFoundException {
             return m_context.getBundle().loadClass(name);
         }
     }
 
+    /**
+     * This class defines the description of primitive (non-composite) component
+     * types. An instance of this class will be returned when invoking the 
+     * {@link ComponentFactory#getComponentDescription()} method.
+     * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+     */
     private final class PrimitiveTypeDescription extends ComponentTypeDescription {
 
         /**
-         * Constructor.
-         * @param factory : the represented factory.
+         * Creates a PrimitiveTypeDescription object.
+         * @param factory the factory attached to this component type description.
          */
         public PrimitiveTypeDescription(Factory factory) {
             super(factory);
         }
 
         /**
-         * Compute the properties to publish : 
-         * component.class contains the pojo class name.
+         * Computes the properties to publish. 
+         * The <code>component.class</code> property contains the implementation class name.
          * @return the dictionary of properties to publish
          * @see org.apache.felix.ipojo.architecture.ComponentTypeDescription#getPropertiesToPublish()
          */
@@ -447,7 +482,7 @@
         }
 
         /**
-         * Add the "implementation-class" attribute to the type description.
+         * Adds the "implementation-class" attribute to the type description.
          * @return the component type description.
          * @see org.apache.felix.ipojo.architecture.ComponentTypeDescription#getDescription()
          */
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java
index 9b6c574..4f2ca74 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ComponentInstance.java
@@ -24,13 +24,13 @@
 import org.osgi.framework.BundleContext;
 
 /**
- * The component instance class manages one instance of a component type.
+ * This class defines the iPOJO's component instance concept.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface ComponentInstance {
 
     /**
-     * Component Instance State : DISPOSED. The instance was destroyed.
+     * Component Instance State : DISPOSED. The component instance was disposed.
      */
     int DISPOSED = -1;
     
@@ -41,87 +41,87 @@
     int STOPPED = 0;
 
     /**
-     * Component Instance State : INVALID. The component is invalid when it
-     * start or when a component dependency is invalid.
+     * Component Instance State : INVALID. The component instance is invalid when it
+     * starts or when a component dependency is invalid.
      */
     int INVALID = 1;
 
     /**
-     * Component Instance State : VALID. The component is resolved when it is
-     * running and all its component dependencies are valid.
+     * Component Instance State : VALID. The component instance is resolved when it is
+     * running and all its attached handlers are valid.
      */
     int VALID = 2;
 
     /**
-     * Start the component instance.
+     * Starts the component instance.
      */
     void start();
 
     /**
-     * Stop the component instance.
+     * Stops the component instance.
      * A stopped instance can be re-started.
      */
     void stop();
     
     /**
-     * Dispose the component instance.
+     * Disposes the component instance.
      * A disposed instance cannot be re-started.
      */
     void dispose();
 
     /**
-     * Return the actual state of the instance. 
+     * Returns the actual state of the instance. 
      * @return the actual state of the component instance.
      */
     int getState();
 
     /**
-     * Return the instance description.
+     * Returns the instance description.
      * @return the instance description of the current instance
      */
     InstanceDescription getInstanceDescription();
 
     /**
-     * Return the factory which create this instance.
+     * Returns the factory who created this instance.
      * @return the factory of the component instance.
      */
     ComponentFactory getFactory();
 
     /**
-     * Return the bundle context of this instance.
+     * Returns the bundle context of this instance.
      * @return the context of the component instance
      */
     BundleContext getContext();
 
     /**
-     * Return the name of the instance.
+     * Returns the name of the instance.
      * @return the name of the component instance
      */
     String getInstanceName();
 
     /**
-     * Check if the instance is started.
-     * @return true if getState returns INVALID or VALID.
+     * Checks if the instance is started.
+     * @return <code>true</code> if {@link ComponentInstance#getState()} 
+     * returns {@link ComponentInstance#INVALID} or {@link ComponentInstance#VALID}.
      */
     boolean isStarted();
 
     /**
-     * Re-configure an instance. Do nothing if the instance does not support
+     * Re-configures an instance. Do nothing if the instance does not support
      * dynamic reconfiguration. The reconfiguration does not stop the instance.
-     * 
-     * @param configuration : the new configuration.
+     * @param configuration the new configuration.
      */
     void reconfigure(Dictionary configuration);
     
     /**
-     * Add an instance state listener on the current instance.
-     * @param listener : the listener to add.
+     * Adds an instance state listener on the current instance.
+     * @param listener the listener to add.
      */
     void addInstanceStateListener(InstanceStateListener listener);
     
     /**
-     * Remove an instance state listener on the current instance.
-     * @param listener : the listener to remove.
+     * Removes an instance state listener on the current instance.
+     * @param listener the listener to remove.
      */
     void removeInstanceStateListener(InstanceStateListener listener);
 
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java
index cde3140..0bed6f4 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ConfigurationException.java
@@ -19,8 +19,9 @@
 package org.apache.felix.ipojo;
 
 /**
- * Configuration Exception.
+ * This class defines the exception thrown when an instance cannot be configured correctly.
  * This exception occurs when component metadata are not correct.
+ * @see Exception
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class ConfigurationException extends Exception {
@@ -31,14 +32,16 @@
     private static final long serialVersionUID = 1L;
     
     /**
-     * Component Type on which the error occurs.
+     * The component type on which the error occurs.
+     * Uses the factory name.
      */
     private String m_type;
     
     /**
-     * Constructor.
-     * @param mes : message
-     * @param typ : component type
+     * Creates a new configuration exception.
+     * @param mes the error message
+     * @param typ the component type
+     * @see Exception#Exception(String)
      */
     ConfigurationException(String mes, String typ) {
         super(mes);
@@ -46,15 +49,16 @@
     }
     
     /**
-     * Constructor.
-     * @param mes : message
+     * Creates a new configuration exception.
+     * @param mes the error message
+     * @see Exception#Exception(String)
      */
     public ConfigurationException(String mes) {
         super(mes);
     }
     
     /**
-     * Get the error message.
+     * Gets the error message.
      * @return the error message.
      * @see java.lang.Throwable#getMessage()
      */
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java
index d592c5c..a2d0fa0 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextListener.java
@@ -20,16 +20,18 @@
 
 
 /**
- * Context Source Listener.
+ * Context Source Listener interface.
+ * A context source listener is notified when a monitored context 
+ * property value changed.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface ContextListener {
     
     /**
      * A monitored value has been modified.
-     * @param source : context source containing the property
-     * @param property : modified property name
-     * @param value : new value of the property
+     * @param source the context source containing the property
+     * @param property the modified property name
+     * @param value the new value of the property
      */
     void update(ContextSource source, String property, Object value);
 
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java
index e55f163..de9a8eb 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/ContextSource.java
@@ -23,34 +23,35 @@
 
 /**
  * Context Source service interface.
+ * A context source advertises of context changes.
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface ContextSource {
     
     /**
-     * Get the current value of the given property.
-     * @param property : property name
-     * @return the property value, null if unknown
+     * Gets the current value of the given property.
+     * @param property property name
+     * @return the property value (<code>null</code> if unknown)
      */
     Object getProperty(String property);
     
     /**
-     * Get the whole context.
+     * Gets the entire context.
      * @return the dictionary [Property, Value]
      */
     Dictionary getContext();
     
     /**
-     * Register a context listener on the given set of properties.
-     * The listener will be notified of every change made on these properties.
-     * @param listener : the context listener to register.
-     * @param properties : property set monitored by the listener.
+     * Registers a context listener on the given set of properties.
+     * The listener will be notified of every changes made on monitored properties.
+     * @param listener the context listener to register.
+     * @param properties property set monitored by the listener.
      */
     void registerContextListener(ContextListener listener, String[] properties);
     
     /**
-     * Unregister the given context listener.
-     * @param listener : the listener to unregister.
+     * Unregisters the given context listener.
+     * @param listener the listener to unregister.
      */
     void unregisterContextListener(ContextListener listener);
 
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java
index a8bff35..84ccf65 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/Factory.java
@@ -32,108 +32,118 @@
 public interface Factory {
 
     /**
-     * Factory State. A valid factory is a factory where all required handlers are available.
+     * Factory State. 
+     * A valid factory is a factory where all required handlers are available.
      */
     int VALID = 1;
 
     /**
-     * Factory State. An invalid factory is a factory where at least one required handler is unavailable. Creating an instance with an invalid factory failed.
+     * Factory State. 
+     * An invalid factory is a factory where at least one required handler is
+     * unavailable. Creating an instance with an invalid factory failed.
      */
     int INVALID = 0;
 
     /**
-     * Create an instance manager (i.e. component type instance).
-     * @param configuration : the configuration properties for this component.
+     * Creates an instance manager (i.e. component type instance).
+     * @param configuration the configuration properties for this component.
      * @return the created instance manager.
-     * @throws UnacceptableConfiguration : when a given configuration is not valid.
-     * @throws MissingHandlerException : when an handler is missing.
-     * @throws ConfigurationException : when the instance configuration failed.
+     * @throws UnacceptableConfiguration if the given configuration is not valid.
+     * @throws MissingHandlerException if an handler is missing.
+     * @throws ConfigurationException if the instance configuration failed.
      */
     ComponentInstance createComponentInstance(Dictionary configuration) throws UnacceptableConfiguration, MissingHandlerException, ConfigurationException;
 
     /**
-     * Create an instance manager (i.e. component type instance). This has these service interaction in the scope given in argument.
-     * @param configuration : the configuration properties for this component.
-     * @param serviceContext : the service context of the component.
+     * Creates an instance manager (i.e. component type instance).
+     * The instance is created in the scope given in argument.
+     * @param configuration the configuration properties for this component.
+     * @param serviceContext the service context of the component.
      * @return the created instance manager.
-     * @throws UnacceptableConfiguration : when the given configuration is not valid.
-     * @throws MissingHandlerException : when an handler is missing.
-     * @throws ConfigurationException : when the instance configuration failed.
+     * @throws UnacceptableConfiguration if the given configuration is not valid.
+     * @throws MissingHandlerException if an handler is missing.
+     * @throws ConfigurationException if the instance configuration failed.
      */
     ComponentInstance createComponentInstance(Dictionary configuration, ServiceContext serviceContext) throws UnacceptableConfiguration, MissingHandlerException, ConfigurationException;
 
     /**
-     * Get the component type information containing provided service, configuration properties ...
+     * Gets the component type information containing provided service, 
+     * configuration properties ...
      * @return the component type information.
      */
     Element getDescription();
 
     /**
-     * Get the component type description.
+     * Gets the component type description.
      * @return the component type description object
      */
     ComponentTypeDescription getComponentDescription();
 
     /**
-     * Check if the given configuration is acceptable as a configuration of a component instance.
-     * @param conf : the configuration to test
-     * @return true if the configuration is acceptable
+     * Checks if the given configuration is acceptable as a configuration
+     * of a component instance.
+     * @param conf the configuration to test
+     * @return <code>true</code> if the configuration is acceptable
      */
     boolean isAcceptable(Dictionary conf);
 
     /**
-     * Return the factory name.
+     * Returns the factory name.
      * @return the name of the factory.
      */
     String getName();
 
     /**
-     * Reconfigure an instance already created. This configuration need to have the name property to identify the instance.
-     * @param conf : the configuration to reconfigure the instance.
-     * @throws UnacceptableConfiguration : if the given configuration is not consistent for the targeted instance.
-     * @throws MissingHandlerException : when an handler is missing.
+     * Reconfigures an instance already created. This configuration needs to 
+     * have the name property to identify the instance.
+     * @param conf the configuration to reconfigure the instance.
+     * @throws UnacceptableConfiguration  if the given configuration is not consistent for the targeted instance.
+     * @throws MissingHandlerException if an handler is missing.
      */
     void reconfigure(Dictionary conf) throws UnacceptableConfiguration, MissingHandlerException;
 
     /**
-     * Add a factory state listener on the current factory.
-     * @param listener : the listener to add
+     * Adds a factory state listener on the current factory.
+     * @param listener the listener to add
      */
     void addFactoryStateListener(FactoryStateListener listener);
 
     /**
-     * Remove the given factory state listener from the listener list.
-     * @param listener : the listener to remove
+     * Removes the given factory state listener from the listener list.
+     * @param listener the listener to remove
      */
     void removeFactoryStateListener(FactoryStateListener listener);
 
     /**
-     * Get the list of missing handlers.
-     * @return the list containing the name of missing handlers (Name : namespace:name)
+     * Gets the list of missing handlers.
+     * The handlers are given under the form namespace:name
+     * @return the list containing the name of missing handlers 
      */
     List getMissingHandlers();
 
     /**
      * Get the list of required handlers.
-     * @return the list containing the name of required handlers (Name : namespace:name)
+     * The handlers are given under the form namespace:name
+     * @return the list containing the name of required handlers 
      */
     List getRequiredHandlers();
 
     /**
-     * Return the classname of the component type.
+     * Returns the class name of the component type.
      * For factories which does not contains a class, return "composite"
      * @return the class name of the component type or "composite"
+     * @deprecated
      */
     String getClassName();
 
     /**
-     * Return the state of the factory.
+     * Returns the state of the factory.
      * @return the state of the factory
      */
     int getState();
 
     /**
-     * Get the bundle context of the factory.
+     * Gets the bundle context of the factory.
      * @return the bundle context of the factory.
      */
     BundleContext getBundleContext();
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java
index 1d3fb59..3d9dadd 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/FactoryStateListener.java
@@ -19,17 +19,18 @@
 package org.apache.felix.ipojo;
 
 /**
- * Factory state listener.
+ * A factory state listener received notification about monitored factory state changes.
  * This listener allows anyone to be notified when the listened factory state changes. 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface FactoryStateListener {
     
     /**
-     * State change listener.
-     * Each time an instance state change, this method is called.
-     * @param factory : changing factory
-     * @param newState : new instance state
+     * Notification listener.
+     * Each time an instance state changes, this method is called
+     * with the new factory state.
+     * @param factory the changing factory
+     * @param newState the new factory state
      */
     void stateChanged(Factory factory, int newState);
 }
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java
index d8d4823..22e308d 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/FieldInterceptor.java
@@ -19,28 +19,30 @@
 package org.apache.felix.ipojo;
 
 /**
-* Field interceptor.
-* A class implementing this interface is able to be notified of field accesses.
-* The listener need to be register on the instance manager. 
-* 
+* A field interceptor is notified when a monitored field asks for a value or
+* receives a new value. A class implementing this interface is able to be 
+* notified of field accesses, and is able to inject a value to this field.
+* The listener needs to be register on the instance manager. 
 * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */
 public interface FieldInterceptor {
     
     /**
-     * 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
+     * This method is called when a PUTFIELD operation is detected,
+     * e.g. an assignation.
+     * @param pojo the pojo object setting the value
+     * @param fieldName the field name
+     * @param value the value passed to the field
      */
     void onSet(Object pojo, String fieldName, Object value);
 
     /**
      * 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
+     * This method allows to inject a value to the field.
+     * @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
      */
     Object onGet(Object pojo, String fieldName, Object value);
 
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java
index 42107af..5d96c33 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/Handler.java
@@ -27,50 +27,51 @@
 
 /**
  * Handler Abstract Class.
- * 
+ * A handler is a 'piece' of 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public abstract class Handler {
 
     /**
-     * Handler namespace property.
+     * The handler namespace property.
      */
     public static final String HANDLER_NAMESPACE_PROPERTY = "handler.namespace";
 
     /**
-     * Handler name property. 
+     * The handler name property. 
      */
     public static final String HANDLER_NAME_PROPERTY = "handler.name";
 
     /**
-     * Handler type property. 
+     * The handler type property. 
      */
     public static final String HANDLER_TYPE_PROPERTY = "handler.type";
 
     /**
-     * Handler priority.
+     * The handler priority.
      */
     public static final String HANDLER_LEVEL_PROPERTY = "handler.level";
 
     /**
-     * Handler validity.
+     * The current handler validity.
+     * This impacts directly the instance state.
      */
     protected boolean m_isValid = true;
 
     /**
-     * HandlerManager managing the current handler.
+     * The HandlerManager managing the current handler.
      */
     protected HandlerManager m_instance;
 
     /**
-     * Set the factory attached to this handler object.
+     * Sets the factory attached to this handler object.
      * This method must be override to depend on each component factory type. 
-     * @param factory : the factory.
+     * @param factory the factory to attach.
      */
     public abstract void setFactory(Factory factory);
 
     /**
-     * Get the logger to use in the handler.
+     * Gets the logger to use in the handler.
      * This method must be override to depend on each component factory type logging policy.
      * @return the logger.
      */
@@ -78,7 +79,8 @@
 
     /**
      * Log method (warning).
-     * @param message : message to log
+     * Log a warning message to the handler logger.
+     * @param message the message to log
      */
     public final void warn(String message) {
         getLogger().log(Logger.WARNING, message);
@@ -86,15 +88,17 @@
 
     /**
      * Log method (error).
-     * @param message : message to log
+     * Log an error message to the handler logger.
+     * @param message the message to log
      */
     public final void error(String message) {
         getLogger().log(Logger.ERROR, message);
     }
 
     /**
-     * Log method (info).
-     * @param message : message to log
+     * Log method (info).     
+     * Log an info message to the handler logger.
+     * @param message the message to log
      */
     public final void info(String message) {
         getLogger().log(Logger.INFO, message);
@@ -102,8 +106,10 @@
 
     /**
      * Log method (warning).
-     * @param message : message to log
-     * @param exception : exception to attach to the message
+     * Log a warning message to the handler logger.
+     * The message is sent with an attached exception.
+     * @param message the message to log
+     * @param exception the exception to attach with the message
      */
     public final void warn(String message, Throwable exception) {
         getLogger().log(Logger.WARNING, message, exception);
@@ -111,8 +117,10 @@
 
     /**
      * Log method (error).
-     * @param message : message to log
-     * @param exception : exception to attach to the message
+     * Log an error message to the handler logger.
+     * The message is sent with an attached exception.
+     * @param message the message to log
+     * @param exception the exception to attach to the message
      */
     public final void error(String message, Throwable exception) {
         getLogger().log(Logger.ERROR, message, exception);
@@ -129,25 +137,25 @@
     public abstract Handler getHandler(String name);
 
     /**
-     * Attach the current handler object to the given component instance.
+     * Attaches the current handler object to the given component instance.
      * An attached handler becomes a part of the instance container.
-     * @param instance : the component instance on which the current handler will be attached.
+     * @param instance the component instance on which the current handler will be attached.
      */
     protected abstract void attach(ComponentInstance instance);
 
     /**
-     * Check if the current handler is valid.
-     * This check test the handlers validity.
+     * Checks if the current handler is valid.
+     * This check tests the handler validity.
      * This method must not be override.
-     * @return true if the handler is valid.
+     * @return <code>true</code> if the handler is valid.
      */
     public final boolean isValid() {
         return ((Pojo) this).getComponentInstance().getState() == ComponentInstance.VALID;
     }
 
     /**
-     * Set the validity of the current handler.
-     * @param isValid : if true the handler becomes valid, else it becomes invalid.
+     * Sets the validity of the current handler.
+     * @param isValid if <code>true</code> the handler becomes valid, else it becomes invalid.
      */
     public final void setValidity(boolean isValid) {
         if (m_isValid != isValid) {
@@ -161,13 +169,17 @@
         }
     }
 
+    /**
+     * Is the current handler valid.
+     * @return <code>true</code> if the handler is valid, <code>false</code> otherwise.
+     */
     public final boolean getValidity() {
         return m_isValid;
     }
 
     /**
-     * Get the component instance of the current handler.
-     * @return : the component instance.
+     * Gets the component instance of the current handler.
+     * @return the component instance.
      */
     public final HandlerManager getHandlerManager() {
         if (m_instance != null) { return m_instance; }
@@ -176,55 +188,66 @@
     }
 
     /**
-     * Initialize component factory.
-     * This method aims to gather component factory properties. Each handler wanting to contribute need to override this 
-     * method and add properties to the given component description.
-     * @param typeDesc : component description.
-     * @param metadata : component type metadata.
-     * @throws ConfigurationException : if the metadata are not correct (early detection).
+     * Initializes the component factory.
+     * This method aims to collect component factory properties. 
+     * Each handler wanting to contribute needs to override this 
+     * method and adds properties to the given component description.
+     * By default, this method does nothing.
+     * @param typeDesc the component description.
+     * @param metadata the component type metadata.
+     * @throws ConfigurationException if the metadata are not correct (early detection).
      */
     public void initializeComponentFactory(ComponentTypeDescription typeDesc, Element metadata) throws ConfigurationException {
         // The default implementation does nothing.
     }
 
     /**
-     * Configure the handler.
-     * @param metadata : the metadata of the component
-     * @param configuration : the instance configuration
-     * @throws ConfigurationException : if the metadata are not correct.
+     * Configures the handler.
+     * @param metadata the metadata of the component
+     * @param configuration the instance configuration
+     * @throws ConfigurationException if the metadata are not correct.
      */
     public abstract void configure(Element metadata, Dictionary configuration) throws ConfigurationException;
 
     /**
-     * Stop the handler : stop the management.
+     * Stops the handler
+     * This method stops the management.
      */
     public abstract void stop();
 
     /**
-     * Start the handler : start the management.
+     * Starts the handler
+     * This method starts the management.
      */
     public abstract void start();
 
     /**
      * This method is called when the component state changed.
-     * @param state : the new state
+     * By default, this method does nothing.
+     * @param state the new instance state {@link ComponentInstance}
      */
     public void stateChanged(int state) {
         // The default implementation does nothing.
     }
 
     /**
-     * Return the current handler description.
+     * Returns the current handler description.
      * The simplest description contains only the name and the validity of the handler.
-     * @return the description of the handler..
+     * If the handler override this method, it can customize the description. 
+     * By default, this method returns the simplest description.
+     * @return the description of the handler.
      */
     public HandlerDescription getDescription() {
         return new HandlerDescription(this);
     }
 
     /**
-     * The instance is reconfiguring.
-     * @param configuration : New instance configuration.
+     * Reconfigures the instance.
+     * This method is called, when the instance is under reconfiguration.
+     * The reconfiguration does not stops the instance, and so the handler supporting
+     * the reconfiguration must override this method and handles this case. 
+     * By default, this method does nothing.
+     * @param configuration the new instance configuration.
      */
     public void reconfigure(Dictionary configuration) {
         // The default implementation does nothing.
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java
index 1c30774..c4a969c 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerFactory.java
@@ -20,13 +20,16 @@
 
 
 /**
- * Service interface published by handler factory. 
+ * Service interface published by handler factory.
+ * This interface allows interacting the the handler factory to create
+ * {@link Handler} objects.
+ * @see Factory 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public interface HandlerFactory extends Factory {
 
     /**
-     * iPOJO Default Namespace.
+     * The iPOJO Default Namespace.
      */
     String IPOJO_NAMESPACE = "org.apache.felix.ipojo";
 
@@ -43,15 +46,15 @@
     String getHandlerName();
 
     /**
-     * Gets the type of created handler.
+     * Gets the type of the handler factory.
      * The handler can only be plugged on instance container with the same type.
-     * Basically, types are primitive and composite.
-     * @return the types of the handler
+     * Basically, types are <code>primitive</code> and <code>composite</code>.
+     * @return the type of the handler
      */
     String getType();
 
     /**
-     * Gets the start level of the handlers created by this factory.
+     * Gets the start level of the handler objects created by this factory.
      * Handlers with a low start level are configured and started before 
      * handlers with an higher start level. Moreover, these handlers are
      * stopped and disposed after.
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java
index b0f0c09..261055e 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManager.java
@@ -27,29 +27,28 @@
 
 /**
  * The handler manager manages an handler instance.
- * 
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 public class HandlerManager extends InstanceManager {
 
     /**
-     * Handler object (contained).
+     * The internal handler object.
      * Immutable once set.
      */
     private Handler m_handler;
 
     /**
-     * Constructor.
-     * @param factory : handler factory
-     * @param context : bundle context
-     * @param handlers : handler array
+     * Creates a handler manager.
+     * @param factory the handler factory
+     * @param context the bundle context
+     * @param handlers the handler array
      */
     public HandlerManager(ComponentFactory factory, BundleContext context, HandlerManager[] handlers) {
         super(factory, context, handlers);
     }
 
     /**
-     * Get the contained handler object.
+     * Gets the contained handler object.
      * If not already created it creates the object.
      * @return the handler object.
      */
@@ -61,10 +60,10 @@
     }
 
     /**
-     * Create and initialize the handler object.
-     * @param instance : component instance on which the handler will be attached.
-     * @param metadata : component metadata.
-     * @param configuration : instance configuration.
+     * Creates and initializes the handler object.
+     * @param instance the component instance on which the handler will be attached.
+     * @param metadata the component metadata.
+     * @param configuration the instance configuration.
      * @throws ConfigurationException if the handler configuration failed.
      */
     public void init(ComponentInstance instance, Element metadata, Dictionary configuration) throws ConfigurationException {
@@ -75,7 +74,7 @@
     }
 
     /**
-     * Create the handler object.
+     * Creates the handler object.
      * This method does nothing if the object is already created.
      * This method does not need locking protocol as only one thread (the creator thread) can create an instance.
      */
@@ -85,7 +84,7 @@
     }
 
     /**
-     * Start the instance manager.
+     * Starts the instance manager.
      */
     public void start() {
         synchronized (this) {
@@ -119,7 +118,7 @@
     }
 
     /**
-     * Stop the instance manager.
+     * Stops the instance manager.
      */
     public void stop() {
         synchronized (this) {
@@ -158,7 +157,7 @@
     }
 
     /** 
-     * Dispose the instance.
+     * Disposes the instance.
      * @see org.apache.felix.ipojo.ComponentInstance#dispose()
      */
     public void dispose() {
@@ -167,7 +166,7 @@
     }
 
     /**
-     * Kill the current instance.
+     * Kills the current instance.
      * Only the factory of this instance can call this method.
      */
     protected void kill() {
@@ -178,8 +177,8 @@
     /**
      * State Change listener callback.
      * This method is notified at each time a plugged handler becomes invalid.
-     * @param instance : changing instance 
-     * @param newState : new state
+     * @param instance the changing instance 
+     * @param newState the new state
      * @see org.apache.felix.ipojo.InstanceStateListener#stateChanged(org.apache.felix.ipojo.ComponentInstance, int)
      */
     public void stateChanged(ComponentInstance instance, int newState) {
diff --git a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java
index a0ba2fa..153ad66 100644
--- a/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java
+++ b/ipojo/core/src/main/java/org/apache/felix/ipojo/HandlerManagerFactory.java
@@ -35,27 +35,28 @@
 public class HandlerManagerFactory extends ComponentFactory implements HandlerFactory {
 
     /**
-     * Handler type (composite|primitive).
+     * The Handler type (<code>composite</code> or <code>primitive</code>).
      */
     private final String m_type;
 
     /**
-     * iPOJO Handler Namespace.
-     * (Set the the iPOJO default namespace is not specified)
+     * The iPOJO Handler Namespace.
+     * (Uses the iPOJO default namespace is not specified)
      */
     private final String m_namespace;
 
     /**
-     * Handler start level.
-     * Lower level are priority are configured and started before higher level, and are stopped after. 
+     * The handler start level.
+     * Lower levels are priority and so are configured and started 
+     * before higher levels, and are stopped after. 
      */
     private final int m_level;
     
     /**
      * Creates a handler factory.
-     * @param context : bundle context
-     * @param metadata : metadata of the component to create
-     * @throws ConfigurationException occurs when the element describing the factory is malformed.
+     * @param context the bundle context
+     * @param metadata the metadata of the component to create
+     * @throws ConfigurationException if the element describing the factory is malformed.
      */
     public HandlerManagerFactory(BundleContext context, Element metadata) throws ConfigurationException {
         super(context, metadata);
@@ -124,12 +125,11 @@
     /**
      * Creates an instance. The given configuration needs to contain the 'name'
      * property. This method is called when holding the lock.
-     * @param configuration : configuration of the created instance.
-     * @param context : the service context to push for this instance.
-     * @param handlers : handler array to used.
-     * @return the created component instance.
-     * not consistent with the component type of this factory.
-     * @throws org.apache.felix.ipojo.ConfigurationException : when the instance configuration failed.
+     * @param configuration the configuration of the created instance.
+     * @param context  the service context to push for this instance.
+     * @param handlers the handler array to attach to the instance.
+     * @return the created {@link HandlerManager}.
+     * @throws org.apache.felix.ipojo.ConfigurationException if the instance configuration failed.
      * @see org.apache.felix.ipojo.Factory#createComponentInstance(java.util.Dictionary)
      */
     public ComponentInstance createInstance(Dictionary configuration, IPojoContext context, HandlerManager[] handlers) throws ConfigurationException {
@@ -142,9 +142,9 @@
     /**
      * Computes required handlers. This method does not manipulate any
      * non-immutable fields, so does not need to be synchronized.
-     * This method is overridden to avoid to use the same detection rules
-     * than atomic components. Indeed, architecture is disable by default,
-     * and an handler is never immediate.
+     * This method is overridden to avoid using the same detection rules
+     * than 'primitive' components. Indeed, architecture is disable by default,
+     * and a handler is never immediate.
      * @return the required handler list.
      */
     public List getRequiredHandlerList() {
@@ -171,20 +171,28 @@
         return list;
     }
 
+    /**
+     * Defines the handler type description.
+     * @see ComponentDescription
+     */
     private class HandlerTypeDescription extends ComponentTypeDescription {
 
         /**
-         * Constructor.
-         * @param factory : factory.
+         * Creates the HandlerTypeDescription.
+         * @param factory the factory.
+         * @see ComponentTypeDescription#ComponentTypeDescription(Factory)
          */
         public HandlerTypeDescription(Factory factory) {
             super(factory);
         }
 
         /**
-         * Add properties to publish : 
-         * handler.name, handler.namespace, handler.type and handler.level if the level is not Integer.MAX.
-         * @return return the dictionary to publish.
+         * Add properties to publish.
+         * <li>handler.name</li>
+         * <li>handler.namespace</li> 
+         * <li>handler.type</li>
+         * <li>handler.level if the level is not Integer.MAX</li>
+         * @return returns the dictionary to publish.
          * @see org.apache.felix.ipojo.architecture.ComponentTypeDescription#getPropertiesToPublish()
          */
         public Dictionary getPropertiesToPublish() {
diff --git a/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java b/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java
index a7391e1..a09e942 100644
--- a/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java
+++ b/ipojo/plugin/src/main/java/org/apache/felix/ipojo/plugin/ManipulatorMojo.java
@@ -29,7 +29,7 @@
 import org.apache.maven.project.MavenProjectHelper;
 
 /**
- * Package an OSGi jar "bundle" as an "iPOJO bundle".
+ * Packages an OSGi jar "bundle" as an "iPOJO bundle".
  *
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  * @version $Rev$, $Date$
@@ -66,7 +66,7 @@
     private String m_jarName;
 
     /**
-     * Metadata file location.
+     * Location of the metadata file.
      * @parameter alias="metadata" default-value="metadata.xml"
      */
     private String m_metadata;
@@ -111,7 +111,7 @@
     }
 
     /**
-     * Execute method : launch the pojoization.
+     * Execute method : this method launches the pojoization.
      * @throws MojoExecutionException : an exception occurs during the manipulation.
      * @see org.apache.maven.plugin.AbstractMojo#execute()
      */