Updated JavaDoc documentation, because it was out of sync with the code (which is a nice way of saying it was plain wrong).

git-svn-id: https://svn.apache.org/repos/asf/incubator/felix/trunk@534521 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/dependencymanager/src/main/java/org/apache/felix/dependencymanager/Service.java b/dependencymanager/src/main/java/org/apache/felix/dependencymanager/Service.java
index a7a1af8..cd6cf9c 100644
--- a/dependencymanager/src/main/java/org/apache/felix/dependencymanager/Service.java
+++ b/dependencymanager/src/main/java/org/apache/felix/dependencymanager/Service.java
@@ -72,22 +72,25 @@
      * There are four special methods that are called when found through
      * reflection to give you some life-cycle management options:
      * <ol>
-     * <li><code>init()</code> when the implementation should be initialized,
-     * before it is actually registered as a service (if at all)</li>
-     * <li><code>start()</code> when the implementation has been registered
-     * as a service (if at all)</li>
-     * <li><code>stop()</code> when the implementation will be stopped, just
-     * before the service will go away (if it had been registered)</li>
-     * <li><code>destroy()</code>after the service has gone away (if it had
-     * been registered)</li>
+     * <li><code>init()</code> is invoked right after the instance has been
+     * created, and before any dependencies are resolved, and can be used to
+     * initialize the internal state of the instance</li>
+     * <li><code>start()</code> is invoked after the required dependencies
+     * are resolved and injected, and before the service is registered</li>
+     * <li><code>stop()</code> is invoked right after the service is
+     * unregistered</li>
+     * <li><code>destroy()</code> is invoked after all dependencies are
+     * removed</li>
      * </ol>
      * In short, this allows you to initialize your instance before it is
      * registered, perform some post-initialization and pre-destruction code
      * as well as final cleanup. If a method is not defined, it simply is not
-     * called, so you can decide which one(s) you need.
+     * called, so you can decide which one(s) you need. If you need even more
+     * fine-grained control, you can register as a service state listener too.
      * 
      * @param implementation the implementation
      * @return this service
+     * @see ServiceStateListener
      */
     public Service setImplementation(Object implementation);
     
diff --git a/dependencymanager/src/main/java/org/apache/felix/dependencymanager/ServiceStateListener.java b/dependencymanager/src/main/java/org/apache/felix/dependencymanager/ServiceStateListener.java
index 0b19c7c..38e8bae 100644
--- a/dependencymanager/src/main/java/org/apache/felix/dependencymanager/ServiceStateListener.java
+++ b/dependencymanager/src/main/java/org/apache/felix/dependencymanager/ServiceStateListener.java
@@ -26,25 +26,30 @@
  */
 public interface ServiceStateListener {
     /**
-     * Called when the service is starting.
+     * Called when the service is starting. At this point, the required
+     * dependencies have been injected, but the service has not been registered
+     * yet.
      * 
      * @param service the service
      */
     public void starting(Service service);
     /**
-     * Called when the service is started.
+     * Called when the service is started. At this point, the service has been
+     * registered.
      * 
      * @param service the service
      */
     public void started(Service service);
     /**
-     * Called when the service is stopping.
+     * Called when the service is stopping. At this point, the service is still
+     * registered.
      * 
      * @param service the service
      */
     public void stopping(Service service);
     /**
-     * Called when the service is stopped.
+     * Called when the service is stopped. At this point, the service has been
+     * unregistered.
      * 
      * @param service the service
      */