diff --git a/akka-actor/src/main/scala/akka/actor/Scheduler.scala b/akka-actor/src/main/scala/akka/actor/Scheduler.scala
index a7d4376114..8104199dec 100644
--- a/akka-actor/src/main/scala/akka/actor/Scheduler.scala
+++ b/akka-actor/src/main/scala/akka/actor/Scheduler.scala
@@ -27,8 +27,8 @@ trait Scheduler {
   /**
    * Schedules a message to be sent repeatedly with an initial delay and
    * frequency. E.g. if you would like a message to be sent immediately and
-   * thereafter every 500ms you would set delay = Duration.Zero and frequency
-   * = Duration(500, TimeUnit.MILLISECONDS)
+   * thereafter every 500ms you would set delay=Duration.Zero and
+   * frequency=Duration(500, TimeUnit.MILLISECONDS)
    *
    * Java & Scala API
    */
diff --git a/akka-actor/src/main/scala/akka/pattern/Patterns.scala b/akka-actor/src/main/scala/akka/pattern/Patterns.scala
index 50e6bb909c..ae359ba795 100644
--- a/akka-actor/src/main/scala/akka/pattern/Patterns.scala
+++ b/akka-actor/src/main/scala/akka/pattern/Patterns.scala
@@ -10,6 +10,7 @@ object Patterns {
   import akka.util.Timeout
 
   /**
+   * <i>Java API for `akka.pattern.ask`:</i>
    * Sends a message asynchronously and returns a [[akka.dispatch.Future]]
    * holding the eventual reply message; this means that the target actor
    * needs to send the result to the `sender` reference provided. The Future
@@ -42,6 +43,7 @@ object Patterns {
   def ask(actor: ActorRef, message: Any): Future[AnyRef] = scalaAsk(actor, message).asInstanceOf[Future[AnyRef]]
 
   /**
+   * <i>Java API for `akka.pattern.ask`:</i>
    * Sends a message asynchronously and returns a [[akka.dispatch.Future]]
    * holding the eventual reply message; this means that the target actor
    * needs to send the result to the `sender` reference provided. The Future
@@ -72,6 +74,7 @@ object Patterns {
   def ask(actor: ActorRef, message: Any, timeout: Timeout): Future[AnyRef] = scalaAsk(actor, message)(timeout).asInstanceOf[Future[AnyRef]]
 
   /**
+   * <i>Java API for `akka.pattern.ask`:</i>
    * Sends a message asynchronously and returns a [[akka.dispatch.Future]]
    * holding the eventual reply message; this means that the target actor
    * needs to send the result to the `sender` reference provided. The Future
diff --git a/akka-actor/src/main/scala/akka/pattern/package.scala b/akka-actor/src/main/scala/akka/pattern/package.scala
index 500beca807..41cba41876 100644
--- a/akka-actor/src/main/scala/akka/pattern/package.scala
+++ b/akka-actor/src/main/scala/akka/pattern/package.scala
@@ -3,6 +3,39 @@
  */
 package akka
 
+/**
+ * == Commonly Used Patterns With Akka ==
+ *
+ * This package is used as a collection point for usage patterns which involve
+ * actors, futures, etc. but are loosely enough coupled to (multiple of) them
+ * to present them separately from the core implementation. Currently supported
+ * are:
+ *
+ * <ul>
+ * <li><b>ask:</b> create a temporary one-off actor for receiving a reply to a
+ * message and complete a [[akka.dispatch.Future]] with it; returns said
+ * Future.</li>
+ * <li><b>pipeTo:</b> feed eventually computed value of a future to an actor as
+ * a message.</li>
+ * </ul>
+ *
+ * In Scala the recommended usage is to import the pattern from the package
+ * object:
+ * {{{
+ * import akka.pattern.ask
+ *
+ * ask(actor, message) // use it directly
+ * actor ask message   // use it by implicit conversion
+ * }}}
+ *
+ * For Java the patterns are available as static methods of the [[akka.pattern.Patterns]]
+ * class:
+ * {{{
+ * import static akka.pattern.Patterns.ask;
+ *
+ * ask(actor, message);
+ * }}}
+ */
 package object pattern {
 
   import akka.actor.{ ActorRef, InternalActorRef, ActorRefWithProvider }