diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java
index 40f77e3..a38245d 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Component.java
@@ -22,8 +22,32 @@
 import java.lang.annotation.Target;
 
 /**
- * This annotation declares a component.
+ * Declares a component type (needed to create instances of the component).
  * This annotation is mandatory to declares an iPOJO component.
+ *
+ * Its usual to find it on top of class definition:
+ * <pre>
+ *     {@code @Component}
+ *     public class MyComponent {
+ *         // ...
+ *     }
+ * </pre>
+ *
+ * But, it is also possible to have it associated to a
+ * {@linkplain org.apache.felix.ipojo.annotations.Stereotype stereotyped} annotation definition:
+ * <pre>
+ *     {@code @Component}
+ *     {@linkplain org.apache.felix.ipojo.annotations.Instantiate @Instantiate}
+ *     {@linkplain org.apache.felix.ipojo.annotations.Stereotype @Stereotype}
+ *     public @interface AutoInstantiatedComponent {
+ *         // ...
+ *     }
+ * </pre>
+ *
+ * <h2>See also</h2>
+ * <ul>
+ *     <li><a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html">Use iPOJO Factories</a></li>
+ * </ul>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -31,44 +55,86 @@
 
     /**
      * Set if the component type is public.
-     * Default: true
+     * @see #publicFactory()
      * @deprecated renamed to publicFactory.
      */
     boolean public_factory() default true;
 
     /**
-     * Set if the component type is public.
-     * Default: true
+     * Set if the component type is public or private (defaults to public).
+     * A private factory does not expose a {@code Factory} service.
+     * Only instances declared in the same bundle are created.
+     * <pre>
+     *     {@code @Component(publicFactory = false)}
+     *     public class MyComponent {
+     *         // ...
+     *     }
+     * </pre>
+     * Default: {@literal true}
      */
     boolean publicFactory() default true;
 
     /**
      * Set the component type name.
+     * <pre>
+     *     {@code @Component(name = "my-component")}
+     *     public class MyComponent {
+     *         // ...
+     *     }
+     * </pre>
      * Default : implementation class name.
      */
     String name() default "";
 
     /**
-     * Enable / Disable the architecture exposition.
-     * Default : true
+     * Enable / Disable the architecture exposition (no {@code Architecture}
+     * service will be exposed for component's instances).
+     * <pre>
+     *     {@code @Component(architecture = false)}
+     *     public class MyComponent {
+     *         // ...
+     *     }
+     * </pre>
+     * Default : {@literal true}
      */
     boolean architecture() default true;
 
     /**
      * Set if the component is immediate.
-     * Default : false
+     * By default, iPOJO tries to be as lazy as possible and will create the POJO instance at the last possible time.
+     * Notice this setting is only effective when the component provides a service ({@linkplain org.apache.felix.ipojo.annotations.Provides @Provides}).
+     * <pre>
+     *     {@code @Component(immediate = true)}
+     *     {@linkplain org.apache.felix.ipojo.annotations.Provides @Provides}
+     *     public class MyComponent implements MyService {
+     *         // ...
+     *     }
+     * </pre>
+     * Default : {@literal false}
      */
     boolean immediate() default false;
 
     /**
-     * Set if the component must propagate received configuration to provided services.
-     * default: true
+     * Enable or disable the configuration propagation to service properties.
+     * <pre>
+     *     {@code @Component(propagation = false)}
+     *     public class MyComponent {
+     *         // ...
+     *     }
+     * </pre>
+     * default: {@literal true}
      */
     boolean propagation() default true;
 
     /**
-     * Set the Managed Service PID.
+     * Set the Managed Service PID for Configuration Admin.
      * default no PID (i.e. the managed service will not be exposed).
+     * <pre>
+     *     {@code @Component(managedservice = "my.Pid")}
+     *     public class MyComponent {
+     *         // ...
+     *     }
+     * </pre>
      */
     String managedservice() default "";
 
@@ -77,6 +143,7 @@
      * from a static method. The specified method must be a static
      * method and return a pojo object.
      * By default, iPOJO uses the 'regular' constructor.
+     * @see #factoryMethod()
      * @deprecated now is called <tt>factoryMethod</tt>.
      */
     String factory_method() default "";
@@ -86,11 +153,26 @@
      * from a static method. The specified method must be a static
      * method and return a pojo object.
      * By default, iPOJO uses the 'regular' constructor.
+     * <pre>
+     *     {@code @Component(factoryMethod = "createInstance")}
+     *     public class MyComponent {
+     *         // ...
+     *         public static MyComponent createInstance() {
+     *             return new MyComponent("some static configuration");
+     *         }
+     *     }
+     * </pre>
      */
     String factoryMethod() default "";
 
     /**
      * Set the version of the component type.
+     * <pre>
+     *     {@code @Component(version = "1.3")}
+     *     public class MyComponent {
+     *         // ...
+     *     }
+     * </pre>
      */
     String version() default "";
 }
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java
index 4f3dc92..babcf01 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Controller.java
@@ -22,7 +22,27 @@
 import java.lang.annotation.Target;
 
 /**
- * This annotation declares a lifecycle controller.
+ * This annotation declares a <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html">lifecycle controller</a>.
+ *
+ * <pre>
+ *     {@code @Component}
+ *     public class MyComponent {
+ *         // ...
+ *         {@code @Controller}
+ *         private boolean controller;
+ *
+ *         public void aMethod() {
+ *             // Invalidate the instance
+ *             controller = false;
+ *         }
+ *
+ *         public void anotherMethod() {
+ *             // Validate the instance again
+ *             controller = true;
+ *         }
+ *     }
+ * </pre>
+
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.FIELD, ElementType.ANNOTATION_TYPE})
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java
index b921267..b3fa777 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Handler.java
@@ -24,6 +24,16 @@
 /**
  * This annotation declares a handler.
  * This annotation is mandatory to declares an iPOJO handler.
+ * <pre>
+ *     {@code @Handler}(
+ *         name = "my-handler",
+ *         namespace = "com.acme.foo"
+ *     )
+ *     public class MyHandler extends PrimitiveHandler {
+ *         // ...
+ *     }
+ * </pre>
+
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -47,7 +57,7 @@
 
     /**
      * Enable / Disable the architecture exposition.
-     * Default : false
+     * Default : {@literal false}
      */
     boolean architecture() default false;
 }
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java
index 608b6bf..1191d47 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/HandlerDeclaration.java
@@ -22,7 +22,14 @@
 import java.lang.annotation.Target;
 
 /**
- * This annotation is used to configure a handler.
+ * This annotation is used to configure a handler through XML (as in {@literal metadata.xml}).
+ * <pre>
+ *     {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ *     {@code @HandlerDeclaration("<ns:my-handler attribute='value' xmlns:ns='http://www.acme.com/ipojo/ns'/>")}
+ *     public class MyComponent {
+ *         // ...
+ *     }
+ * </pre>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -31,6 +38,7 @@
     /**
      * The content of this attribute represents the XML 
      * that would be used in the metadata.xml.
+     * It must be a root XML Element, namespaces are allowed and so for child elements.
      */
     String value();
 }
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java
index 90b0b7b..87d9201 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Instantiate.java
@@ -24,6 +24,17 @@
 /**
  * This annotation is used to create an 'empty' instance of the
  * current component type.
+ *
+ * Notice that all mandatory properties should have a default value, otherwise
+ * configuration is declared unacceptable and the instance creation fails.
+ *
+ * <pre>
+ *     {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ *     {@code @Instantiate}
+ *     public class MyComponent {
+ *         // ...
+ *     }
+ * </pre>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@@ -31,7 +42,14 @@
     
     /**
      * Optional attribute to set the instance name.
-     * Default: no name
+     * Default: unique generated name
+     * <pre>
+     *     {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+     *     {@code @Instantiate("my-default-component")}
+     *     public class MyComponent {
+     *         // ...
+     *     }
+     * </pre>
      */
     String name() default ""; 
 }
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java
index 01b0c66..0dfac8c 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Invalidate.java
@@ -23,6 +23,13 @@
 
 /**
  * This annotation declares an invalidate callback.
+ *
+ * <pre>
+ *     {@code @Invalidate}
+ *     public void stop() {
+ *         // Code executed when instances are becoming invalid
+ *     }
+ * </pre>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java
index e4a65c6..0319439 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostRegistration.java
@@ -23,8 +23,16 @@
 
 
 /**
- * This annotation declares a post-service-registration method.
+ * Declares a method to be <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html#being-notified-of-the-service-registration-and-unregistration">notified after service registration</a> is effective.
+ *
+ * <pre>
+ *     {@code @PostRegistration}
+ *     public void registered(ServiceReference<?> reference) {
+ *         // Called after the service publication
+ *     }
+ * </pre>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ * @see org.apache.felix.ipojo.annotations.Provides
  */
 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
 public @interface PostRegistration {
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java
index ce9208e..50f7040 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/PostUnregistration.java
@@ -23,8 +23,16 @@
 
 
 /**
- * This annotation declares a post-service-unregistration method.
+ * Declares a method to be <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html#being-notified-of-the-service-registration-and-unregistration">notified after service un-registration</a> is effective.
+ *
+ * <pre>
+ *     {@code @PostUnregistration}
+ *     public void unregistered(ServiceReference<?> reference) {
+ *         // Called after the service un-publication
+ *     }
+ * </pre>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ * @see org.apache.felix.ipojo.annotations.Provides
  */
 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
 public @interface PostUnregistration {
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java
index 1db18f5..d0f06ee 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Provides.java
@@ -22,36 +22,71 @@
 import java.lang.annotation.Target;
 
 /**
-* This annotation declares that the component instances will provide a service.
-* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
+ * This annotation declares that the component instances will provide a service.
+ *
+ * <pre>
+ *     {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+ *     {@code @Provides}
+ *     public class MyComponent implements Service {
+ *         // ...
+ *     }
+ * </pre>
+ * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
 */
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
 public @interface Provides {
 
     /**
      * Set the provided specifications.
+     * It can be used to force the exposed service to use an implementation class
+     * (not an interface) as specification.
      * Default : all implemented interfaces
+     *
+     * <pre>
+     *     {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+     *     {@code @Provides(specifications = AbsComponent.class)}
+     *     public class MyComponent extends AbsComponent {
+     *         // ...
+     *     }
+     * </pre>
      */
     Class[] specifications() default { };
 
     /**
      * Set the service object creation strategy.
-     * Two value are possible: SINGLETON, SERVICE, METHOD, INSTANCE or the strategy class name.
-     * SERVICE means OSGi Service Factory.
-     * METHOD delegates the creation to the factory-method of the component
-     * INSTANCE creates one service object per requiring instance
-     * for other strategies, specify the qualified name of the CreationStrategy class.
-     * Default : SINGLETON
+     * Multiple values are possible: {@literal SINGLETON}, {@literal SERVICE},
+     * {@literal METHOD}, {@literal INSTANCE} or the strategy fully qualified class name:
+     * <ul>
+     *     <li>{@literal SINGLETON}: Default strategy</li>
+     *     <li>{@literal SERVICE}: OSGi Service Factory style, 1 POJO instance per consumer bundle</li>
+     *     <li>{@literal METHOD}: Delegates the creation to the factory-method of the component, method will be called every time the service reference is get.</li>
+     *     <li>{@literal INSTANCE}: Creates one service object per requiring instance</li>
+     *     <li>Any other value is interpreted as the qualified name of a {@code CreationStrategy} implementation</li>
+     * </ul>
      */
     String strategy() default "SINGLETON";
 
     /**
      * Allows adding static properties to the service.
-     * Nested properties are static service properties,
-     * so <b>must</b> contain the name and the value as
-     * they are not attached to a field.
+     * Nested properties are static service properties, so <b>must</b> contain the name,
+     * value and type as they are not attached to a field (cannot discover type through
+     * introspection).
      * The array contains {@link StaticServiceProperty} elements.
      * Default : No service properties
+
+     * <pre>
+     *     {@linkplain org.apache.felix.ipojo.annotations.Component @Component}
+     *     {@code @Provides}(
+     *         properties = {
+     *             {@code @StaticServiceProperty}(name = "size", type = "int", value = "5"),
+     *             {@code @StaticServiceProperty}(name = "name", type = "java.lang.String", value = "OSGi")
+     *         }
+     *     )
+     *     public class MyComponent implements Service {
+     *         // ...
+     *     }
+     * </pre>
+
      */
     StaticServiceProperty[] properties() default {};
 }
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java
index 8abff5e..5fa9270 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Updated.java
@@ -23,7 +23,22 @@
 
 /**
  * This annotation declares an updated callback.
- * Updated callback are called after a reconfiguration.
+ * Updated callback are called after a <a href="http://felix.apache.org/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html#being-notified-when-a-reconfiguration-is-completed">reconfiguration</a>.
+ *
+ * Methods annotated with {@code @Updated} must have one of the 2 following signatures:
+ * <pre>
+ *     {@code @Updated}
+ *     public void updated() {
+ *         // The instance was reconfigured
+ *     }
+ * </pre>
+ *
+ * <pre>
+ *     {@code @Updated}
+ *     public void updated(Dictionary conf) {
+ *         // The instance was reconfigured, conf is the new configuration.
+ *     }
+ * </pre>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
diff --git a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java
index aaaa321..3a6517e 100644
--- a/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java
+++ b/ipojo/manipulator/annotations/src/main/java/org/apache/felix/ipojo/annotations/Validate.java
@@ -23,6 +23,13 @@
 
 /**
  * This annotation declares a validate callback.
+ *
+ * <pre>
+ *     {@code @Validate}
+ *     public void start() {
+ *         // Code executed when instances are becoming valid
+ *     }
+ * </pre>
  * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
  */
 @Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})