fixed some javadocs
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@1132960 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Inject.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Inject.java
index 0c90be7..e97c627 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Inject.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Inject.java
@@ -27,11 +27,51 @@
* Inject classes in a component instance field.
* The following injections are currently performed, depending on the type of the
* field this annotation is applied on:
- * <dl>
- * <dt>BundleContext</dt><dd>the bundle context of the bundle</dd>
- * <dt>DependencyManager</dt><dd>the dependency manager instance</dd>
- * <dt>Component</dt><dd>the component instance of the dependency manager</dd>
- * </dl>
+ * <ul>
+ * <li>BundleContext: the bundle context of the bundle
+ * <li>DependencyManager: the dependency manager instance
+ * <li>Component: the component instance of the dependency manager
+ * </ul>
+ *
+ * <p>
+ * <h3>Usage Examples</h3>
+ * <blockquote>
+ *
+ * <pre>
+ * @Component
+ * class X implements Z {
+ * @Inject
+ * BundleContext bundleContext;
+ *
+ * @Inject
+ * Component component;
+ *
+ * @Inject
+ * DependencyManager manager;
+ *
+ * OtherService otherService;
+ *
+ * @Init
+ * void init() {
+ * System.out.println("Bundle Context: " + bundleContext);
+ * System.out.println("Manager: " + manager);
+ *
+ * // Use DM API for defining an extra service dependency
+ * componnent.add(manager.createServiceDependency()
+ * .setService(OtherService.class)
+ * .setRequired(true)
+ * .setInstanceBound(true));
+ * }
+ *
+ * @Start
+ * void start() {
+ * System.out.println("OtherService: " + otherService);
+ * }
+ * }
+ * </pre>
+ * </blockquote>
+ *
+ * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.FIELD)
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Property.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Property.java
index cd9a6a8..5c589b5 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Property.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Property.java
@@ -26,6 +26,11 @@
/**
* Annotation used to describe a property key-value pair. It is used when
* declaring {@link Component#properties()} attribute.
+ * This annotation only support properties which type is either a
+ * String, or a String array.
+ * If you need to specify some properties with types other than Strings,
+ * then use the {@link Start} annotation, which allows to annotate a <code>start</code>
+ * method which may optionally return a Map of any service property types.
*
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@@ -46,7 +51,7 @@
String value() default "";
/**
- * Returns the property values as a String array).
+ * Returns the property value as a String array.
* @return this property value as a String array
*/
String[] values() default {};
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Registered.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Registered.java
index 52676cc..5c34855 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Registered.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Registered.java
@@ -29,6 +29,26 @@
* When a service is registered, the ServiceRegistration used to register the service is
* also passed to the method (if it takes a ServiceRegistration as parameter).
*
+ * <p>
+ * <h3>Usage Examples</h3>
+ * <blockquote>
+ *
+ * <pre>
+ * @Component
+ * class X implements Z {
+ * @Start
+ * void start() {
+ * // Our Z Service is about to be registered into the OSGi registry.
+ * }
+ *
+ * @Registered
+ * void registered(ServiceRegistration sr) {
+ * // At this point, our service has been registered into the registry.
+ * }
+ * }
+ * </pre>
+ * </blockquote>
+ *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Retention(RetentionPolicy.CLASS)
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Start.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Start.java
index 2d65c24..da61b70 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Start.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Start.java
@@ -45,7 +45,10 @@
* // Our Z Service is ready (all required dependencies have been satisfied), and is about to be
* // registered into the OSGi registry. We return here an optional Map containing some extra-properties
* // which will be appended to the properties supplied in the Component annotation.
- * return new HashMap() {{ put("foo2", "bar2"); }};
+ * return new HashMap() {{
+ * put("foo2", "bar2");
+ * put(Constants.SERVICE_RANKING, Integer.valueOf(10));
+ * }};
* }
* }
* </pre>
diff --git a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Unregistered.java b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Unregistered.java
index 4215dbd..c59a435 100644
--- a/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Unregistered.java
+++ b/dependencymanager/annotation/src/main/java/org/apache/felix/dm/annotation/api/Unregistered.java
@@ -28,6 +28,26 @@
* At this point, the component has been unregistered from the OSGI registry (if it provides some services).
* The method must not take any parameters.
*
+ * <p>
+ * <h3>Usage Examples</h3>
+ * <blockquote>
+ *
+ * <pre>
+ * @Component
+ * class X implements Z {
+ * @Stop
+ * void stop(ServiceRegistration sr) {
+ * // Our service must stop because it is about to be unregistered from the registry.
+ * }
+ *
+ * @Unregistered
+ * void unregistered() {
+ * // At this point, our service has been unregistered from the OSGi registry
+ * }
+ * }
+ * </pre>
+ * </blockquote>
+ *
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
@Retention(RetentionPolicy.CLASS)