diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala b/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala
index 65e8190c17..0e2ca2e000 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala
@@ -172,20 +172,20 @@ object Source {
     new Source(scaladsl.Source.repeat(element))
 
   /**
-   * create a `Source` that will unfold a value of type `S` into
+   * Create a `Source` that will unfold a value of type `S` into
    * a pair of the next state `S` and output elements of type `E`.
    */
   def unfold[S, E](s: S, f: function.Function[S, Option[(S, E)]]): Source[E, Unit] =
     new Source(scaladsl.Source.unfold(s)((s: S) ⇒ f.apply(s)))
 
   /**
-   * same as unfold, but uses an async function to generate the next state-element tuple.
+   * Same as [[unfold]], but uses an async function to generate the next state-element tuple.
    */
   def unfoldAsync[S, E](s: S, f: function.Function[S, Future[Option[(S, E)]]]): Source[E, Unit] =
     new Source(scaladsl.Source.unfoldAsync(s)((s: S) ⇒ f.apply(s)))
 
   /**
-   * simpler unfold, for infinite sequences.
+   * Simpler [[unfold]], for infinite sequences.
    */
   def unfoldInf[S, E](s: S, f: function.Function[S, (S, E)]): Source[E, Unit] = {
     new Source(scaladsl.Source.unfoldInf(s)((s: S) ⇒ f.apply(s)))
diff --git a/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala b/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala
index 7221edb022..9b96bb8d00 100644
--- a/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala
+++ b/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala
@@ -245,15 +245,15 @@ object Source {
   }
 
   /**
-   * create a `Source` that will unfold a value of type `S` into
+   * Create a `Source` that will unfold a value of type `S` into
    * a pair of the next state `S` and output elements of type `E`.
    *
-   * for example, all the fibonacci numbers under 10M:
+   * For example, all the Fibonacci numbers under 10M:
    *
    * {{{
-   *   Source.unfold(0 → 1){
-   *    case (a,_) if a > 10000000 ⇒ None
-   *    case (a,b) ⇒ Some((b → (a + b)) → a)
+   *   Source.unfold(0 → 1) {
+   *    case (a, _) if a > 10000000 ⇒ None
+   *    case (a, b) ⇒ Some((b → (a + b)) → a)
    *   }
    * }}}
    */
@@ -261,14 +261,14 @@ object Source {
     Source.fromGraph(new Unfold(s, f)).withAttributes(DefaultAttributes.unfold)
 
   /**
-   * same as unfold, but uses an async function to generate the next state-element tuple.
+   * Same as [[unfold]], but uses an async function to generate the next state-element tuple.
    *
    * async fibonacci example:
    *
    * {{{
-   *   Source.unfoldAsync(0 → 1){
-   *    case (a,_) if a > 10000000 ⇒ Future.successful(None)
-   *    case (a,b) ⇒ Future{
+   *   Source.unfoldAsync(0 → 1) {
+   *    case (a, _) if a > 10000000 ⇒ Future.successful(None)
+   *    case (a, b) ⇒ Future{
    *      Thread.sleep(1000)
    *      Some((b → (a + b)) → a)
    *    }
@@ -279,11 +279,11 @@ object Source {
     Source.fromGraph(new UnfoldAsync(s, f)).withAttributes(DefaultAttributes.unfoldAsync)
 
   /**
-   * simpler unfold, for infinite sequences.
+   * Simpler [[unfold]], for infinite sequences.
    *
    * {{{
-   *   Source.unfoldInf(0 → 1){
-   *    case (a,b) ⇒ (b → (a + b)) → a
+   *   Source.unfoldInf(0 → 1) {
+   *    case (a, b) ⇒ (b → (a + b)) → a
    *   }
    * }}}
    */