diff --git a/akka-actor/src/main/scala/akka/actor/Props.scala b/akka-actor/src/main/scala/akka/actor/Props.scala
index 323c338196..404966d88f 100644
--- a/akka-actor/src/main/scala/akka/actor/Props.scala
+++ b/akka-actor/src/main/scala/akka/actor/Props.scala
@@ -10,10 +10,9 @@ import akka.util._
 import collection.immutable.Stack
 
 /**
- * ActorRef configuration object, this is threadsafe and fully sharable
- *
- * Props() returns default configuration
- * FIXME document me
+ * Factory for Props instances.
+ * Props is a ActorRef configuration object, that is thread safe and fully sharable.
+ * Used when creating new actors through; <code>ActorSystem.actorOf</code> and <code>ActorContext.actorOf</code>.
  */
 object Props {
   import FaultHandlingStrategy._
@@ -28,54 +27,81 @@ object Props {
     case _                               ⇒ Escalate
   }
   final val defaultFaultHandler: FaultHandlingStrategy = OneForOneStrategy(defaultDecider, None, None)
-
   final val noHotSwap: Stack[Actor.Receive] = Stack.empty
+  final val empty = Props(new Actor { def receive = Actor.emptyBehavior })
 
   /**
-   * The default Props instance, uses the settings from the Props object starting with default*
+   * The default Props instance, uses the settings from the Props object starting with default*.
    */
   final val default = new Props()
 
   /**
-   * Returns a cached default implementation of Props
+   * Returns a cached default implementation of Props.
    */
   def apply(): Props = default
 
-  val empty = Props(new Actor { def receive = Actor.emptyBehavior })
-
   /**
    * Returns a Props that has default values except for "creator" which will be a function that creates an instance
-   * of the supplied type using the default constructor
+   * of the supplied type using the default constructor.
    */
   def apply[T <: Actor: ClassManifest]: Props =
     default.withCreator(implicitly[ClassManifest[T]].erasure.asInstanceOf[Class[_ <: Actor]].newInstance)
 
   /**
    * Returns a Props that has default values except for "creator" which will be a function that creates an instance
-   * of the supplied class using the default constructor
+   * of the supplied class using the default constructor.
    */
   def apply(actorClass: Class[_ <: Actor]): Props =
     default.withCreator(actorClass.newInstance)
 
   /**
    * Returns a Props that has default values except for "creator" which will be a function that creates an instance
-   * using the supplied thunk
+   * using the supplied thunk.
    */
-  def apply(creator: ⇒ Actor): Props = default.withCreator(creator)
+  def apply(creator: ⇒ Actor): Props =
+    default.withCreator(creator)
 
   /**
    * Returns a Props that has default values except for "creator" which will be a function that creates an instance
-   * using the supplied thunk
+   * using the supplied thunk.
    */
-  def apply(creator: Creator[_ <: Actor]): Props = default.withCreator(creator.create)
+  def apply(creator: Creator[_ <: Actor]): Props =
+    default.withCreator(creator.create)
 
-  def apply(behavior: ActorContext ⇒ Actor.Receive): Props = apply(new Actor { def receive = behavior(context) })
+  def apply(behavior: ActorContext ⇒ Actor.Receive): Props =
+    apply(new Actor { def receive = behavior(context) })
 
-  def apply(faultHandler: FaultHandlingStrategy): Props = apply(new Actor { def receive = { case _ ⇒ } }).withFaultHandler(faultHandler)
+  def apply(faultHandler: FaultHandlingStrategy): Props =
+    apply(new Actor { def receive = { case _ ⇒ } }).withFaultHandler(faultHandler)
 }
 
 /**
- * ActorRef configuration object, this is thread safe and fully sharable
+ * Props is a ActorRef configuration object, that is thread safe and fully sharable.
+ * Used when creating new actors through; <code>ActorSystem.actorOf</code> and <code>ActorContext.actorOf</code>.
+ *
+ * Examples on Scala API:
+ * {{{
+ *  val props = Props[MyActor]
+ *  val props = Props(new MyActor)
+ *  val props = Props[MyActor].withTimeout(timeout)
+ *  val props = Props[MyActor].withFaultHandler(OneForOneStrategy {
+ *    case e: IllegalStateException ⇒ Resume
+ *  })
+ * }}}
+ *
+ * Examples on Java API:
+ * {{{
+ *  Props props = new Props();
+ *  Props props = new Props(MyActor.class);
+ *  Props props = new Props(new UntypedActorFactory() {
+ *    public UntypedActor create() {
+ *      return new MyActor();
+ *    }
+ *  });
+ *  Props props = new Props().withCreator(new UntypedActorFactory() { ... });
+ *  Props props = new Props().withTimeout(timeout);
+ *  Props props = new Props().withFaultHandler(new OneForOneStrategy(...));
+ * }}}
  */
 case class Props(creator: () ⇒ Actor = Props.defaultCreator,
                  @transient dispatcher: MessageDispatcher = Props.defaultDispatcher,
@@ -83,26 +109,8 @@ case class Props(creator: () ⇒ Actor = Props.defaultCreator,
                  faultHandler: FaultHandlingStrategy = Props.defaultFaultHandler) {
 
   /**
-   * Java API
-   */
-  def this(factory: UntypedActorFactory) = this(
-    creator = () ⇒ factory.create(),
-    dispatcher = Props.defaultDispatcher,
-    timeout = Props.defaultTimeout,
-    faultHandler = Props.defaultFaultHandler)
-
-  /**
-   * Java API
-   */
-  def this(actorClass: Class[_ <: Actor]) = this(
-    creator = () ⇒ actorClass.newInstance,
-    dispatcher = Props.defaultDispatcher,
-    timeout = Props.defaultTimeout,
-    faultHandler = Props.defaultFaultHandler)
-
-  /**
-   * No-args constructor that sets all the default values
-   * Java API
+   * No-args constructor that sets all the default values.
+   * Java API.
    */
   def this() = this(
     creator = Props.defaultCreator,
@@ -111,39 +119,56 @@ case class Props(creator: () ⇒ Actor = Props.defaultCreator,
     faultHandler = Props.defaultFaultHandler)
 
   /**
-   * Returns a new Props with the specified creator set
-   *  Scala API
+   * Java API.
+   */
+  def this(factory: UntypedActorFactory) = this(
+    creator = () ⇒ factory.create(),
+    dispatcher = Props.defaultDispatcher,
+    timeout = Props.defaultTimeout,
+    faultHandler = Props.defaultFaultHandler)
+
+  /**
+   * Java API.
+   */
+  def this(actorClass: Class[_ <: Actor]) = this(
+    creator = () ⇒ actorClass.newInstance,
+    dispatcher = Props.defaultDispatcher,
+    timeout = Props.defaultTimeout,
+    faultHandler = Props.defaultFaultHandler)
+
+  /**
+   * Returns a new Props with the specified creator set.
+   * Scala API.
    */
   def withCreator(c: ⇒ Actor) = copy(creator = () ⇒ c)
 
   /**
-   * Returns a new Props with the specified creator set
-   *  Java API
+   * Returns a new Props with the specified creator set.
+   * Java API.
    */
   def withCreator(c: Creator[Actor]) = copy(creator = () ⇒ c.create)
 
   /**
-   * Returns a new Props with the specified creator set
-   *  Java API
+   * Returns a new Props with the specified creator set.
+   * Java API.
    */
   def withCreator(c: Class[_ <: Actor]) = copy(creator = () ⇒ c.newInstance)
 
   /**
-   * Returns a new Props with the specified dispatcher set
-   *  Java API
+   * Returns a new Props with the specified dispatcher set.
+   * Java API.
    */
   def withDispatcher(d: MessageDispatcher) = copy(dispatcher = d)
 
   /**
    * Returns a new Props with the specified timeout set
-   * Java API
+   * Java API.
    */
   def withTimeout(t: Timeout) = copy(timeout = t)
 
   /**
-   * Returns a new Props with the specified faulthandler set
-   * Java API
+   * Returns a new Props with the specified faulthandler set.
+   * Java API.
    */
   def withFaultHandler(f: FaultHandlingStrategy) = copy(faultHandler = f)
-
 }