From 4e796a5eecc0f7e072c1cbd8e399de33b8ac3fef Mon Sep 17 00:00:00 2001
From: Konrad Malawski <konrad.malawski@typesafe.com>
Date: Tue, 7 Apr 2015 15:51:23 +0200
Subject: [PATCH 1/2] +str #17108 adds arity-numbers to javadsl for nicer
 compile errors Resolves #17108

---
 .../akka/stream/javadsl/FlexiMergeTest.java   |  1 +
 .../akka/stream/javadsl/FlowGraphTest.java    |  2 +-
 .../javadsl/BidiFlowCreate.scala.template     |  9 +++++--
 .../stream/javadsl/FlowCreate.scala.template  |  6 ++++-
 .../stream/javadsl/GraphCreate.scala.template | 14 ++++++++---
 .../stream/javadsl/SinkCreate.scala.template  | 25 ++++++++++++++-----
 .../javadsl/SourceCreate.scala.template       | 25 +++++++++++++++++--
 .../stream/javadsl/ZipWith.scala.template     |  5 ++--
 8 files changed, 68 insertions(+), 19 deletions(-)

diff --git a/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java b/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java
index 33cd41f2e4..aee0acc752 100644
--- a/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java
+++ b/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java
@@ -7,6 +7,7 @@ import java.util.Arrays;
 import java.util.List;
 import java.util.HashSet;
 
+import akka.stream.javadsl.japi.Function;
 import org.junit.ClassRule;
 import org.junit.Test;
 
diff --git a/akka-stream-tests/src/test/java/akka/stream/javadsl/FlowGraphTest.java b/akka-stream-tests/src/test/java/akka/stream/javadsl/FlowGraphTest.java
index 83b4c62d8c..1c1a51f8c2 100644
--- a/akka-stream-tests/src/test/java/akka/stream/javadsl/FlowGraphTest.java
+++ b/akka-stream-tests/src/test/java/akka/stream/javadsl/FlowGraphTest.java
@@ -222,7 +222,7 @@ public class FlowGraphTest extends StreamTest {
     final Source<Integer, BoxedUnit> in3 = Source.single(100);
     final Source<Integer, BoxedUnit> in4 = Source.single(1000);
 
-    final Graph<FanInShape4<Integer, Integer, Integer, Integer, Integer>, BoxedUnit> sumZip = ZipWith.create(
+    final Graph<FanInShape4<Integer, Integer, Integer, Integer, Integer>, BoxedUnit> sumZip = ZipWith.create4(
             new Function4<Integer, Integer, Integer, Integer, Integer>() {
               @Override public Integer apply(Integer i1, Integer i2, Integer i3, Integer i4) throws Exception {
                 return i1 + i2 + i3 + i4;
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template
index eb8641d4a8..efabe898a7 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template
@@ -16,10 +16,15 @@ trait BidiFlowCreate {
   def create[I1, O1, I2, O2](block: japi.Function[FlowGraph.Builder[Unit], BidiShape[I1, O1, I2, O2]]): BidiFlow[I1, O1, I2, O2, Unit] =
     new BidiFlow(scaladsl.BidiFlow() { b ⇒ block.apply(b.asJava) })
 
-  def create[I1, O1, I2, O2, S <: Shape, M](g1: Graph[S, M], block: japi.Function2[FlowGraph.Builder[M], S, BidiShape[I1, O1, I2, O2]]): BidiFlow[I1, O1, I2, O2, M] =
+  def create[I1, O1, I2, O2, S <: Shape, M](g1: Graph[S, M],
+      block: japi.Function2[FlowGraph.Builder[M], S, BidiShape[I1, O1, I2, O2]]): BidiFlow[I1, O1, I2, O2, M] =
     new BidiFlow(scaladsl.BidiFlow(g1) { b ⇒ s => block.apply(b.asJava, s) })
 
-  [2..21#def create[I##1, O##1, I##2, O##2, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  def create[I1, O1, I2, O2, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
+      block: japi.Function3[FlowGraph.Builder[M], S1, S2, BidiShape[I1, O1, I2, O2]]): BidiFlow[I1, O1, I2, O2, M] =
+    new BidiFlow(scaladsl.BidiFlow(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) })
+
+  [3..21#def create1[I##1, O##1, I##2, O##2, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], BidiShape[I##1, O##1, I##2, O##2]]): BidiFlow[I##1, O##1, I##2, O##2, M] =
     new BidiFlow(scaladsl.BidiFlow([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) })#
   
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template
index 64ca7ddd32..969287cdd3 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template
@@ -19,7 +19,11 @@ trait FlowCreate {
   def create[I, O, S <: Shape, M](g1: Graph[S, M], block: japi.Function2[FlowGraph.Builder[M], S, Inlet[I] Pair Outlet[O]]): Flow[I, O, M] =
     new Flow(scaladsl.Flow(g1) { b ⇒ s => block.apply(b.asJava, s) })
 
-  [2..21#def create[I, O, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  def create[I, O, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
+      block: japi.Function3[FlowGraph.Builder[M], S1, S2, Inlet[I] Pair Outlet[O]]): Flow[I, O, M] =
+    new Flow(scaladsl.Flow(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) })
+
+  [3..21#def create1[I, O, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], Inlet[I] Pair Outlet[O]]): Flow[I, O, M] =
     new Flow(scaladsl.Flow([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) })#
   
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template
index 37cf4a82b1..56c66a30c1 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template
@@ -18,17 +18,23 @@ trait GraphCreate {
   def partial[S <: Shape](block: japi.Function[FlowGraph.Builder[Unit], S]): Graph[S, Unit] =
     scaladsl.FlowGraph.partial() { b ⇒ block.apply(b.asJava) }
 
-  def closed[S1 <: Shape, M](g1: Graph[S1, M], block: japi.Procedure2[FlowGraph.Builder[M], S1]): RunnableFlow[M] =
+  def closed[S1 <: Shape, M](g1: Graph[S1, M],
+      block: japi.Procedure2[FlowGraph.Builder[M], S1]): RunnableFlow[M] =
     scaladsl.FlowGraph.closed(g1) { b ⇒ s => block.apply(b.asJava, s) }
 
-  def partial[S1 <: Shape, S <: Shape, M](g1: Graph[S1, M], block: japi.Function2[FlowGraph.Builder[M], S1, S]): Graph[S, M] =
+  def partial[S1 <: Shape, S <: Shape, M](g1: Graph[S1, M],
+      block: japi.Function2[FlowGraph.Builder[M], S1, S]): Graph[S, M] =
     scaladsl.FlowGraph.partial(g1) { b ⇒ s => block.apply(b.asJava, s) }
 
-  [2..21#def closed[[#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  def closed[S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
+      block: japi.Procedure3[FlowGraph.Builder[M], S1, S2]): RunnableFlow[M] =
+    scaladsl.FlowGraph.closed(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) }
+
+  [3..21#def closed1[[#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Procedure2[FlowGraph.Builder[M], [#S1#]]): RunnableFlow[M] =
     scaladsl.FlowGraph.closed([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) }
     
-  def partial[[#S1 <: Shape#], S <: Shape, [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  def partial1[[#S1 <: Shape#], S <: Shape, [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], S]): Graph[S, M] =
     scaladsl.FlowGraph.partial([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) }#
   
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
index fa33ff0a54..ae1386d432 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
@@ -10,20 +10,33 @@ import akka.stream.scaladsl.JavaConverters._
 trait SinkCreate {
 
   /**
-   * Creates a `Sink` by using a `FlowGraph.Builder` on a block that expects
-   * a [[FlowGraph.Builder]] and returns the `UndefinedSource`.
+   * Creates a `Sink` by using a `FlowGraph.Builder[Unit]` on a block that expects
+   * a [[FlowGraph.Builder]] and returns an [[Inlet]].
    */
   def create[T](block: japi.Function[FlowGraph.Builder[Unit], Inlet[T]]): Sink[T, Unit] =
     new Sink(scaladsl.Sink() { b ⇒ block.apply(b.asJava) })
 
   /**
-   * Creates a `Sink` by using a `FlowGraph.Builder` on a block that expects
-   * a [[FlowGraph.Builder]] and returns the `UndefinedSource`.
+   * Creates a `Sink` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 1 graph and then returns an [[Inlet]].
    */
-  def create[T, S <: Shape, M](g1: Graph[S, M], block: japi.Function2[FlowGraph.Builder[M], S, Inlet[T]]): Sink[T, M] =
+  def create[T, S <: Shape, M](g1: Graph[S, M],
+      block: japi.Function2[FlowGraph.Builder[M], S, Inlet[T]]): Sink[T, M] =
     new Sink(scaladsl.Sink(g1) { b ⇒ s => block.apply(b.asJava, s) })
 
-  [2..21#def create[T, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  /**
+   * Creates a `Sink` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 2 graphs and then returns an [[Inlet]].
+   */
+   def create[T, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
+      block: japi.Function3[FlowGraph.Builder[M], S1, S2, Inlet[T]]): Sink[T, M] =
+    new Sink(scaladsl.Sink(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) })
+
+  [3..21#/**
+   * Creates a `Sink` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 1 graphs and then returns an [[Inlet]].
+   */
+  def create1[T, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], Inlet[T]]): Sink[T, M] =
     new Sink(scaladsl.Sink([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) })#
   
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template
index e12a470106..1063facbc8 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template
@@ -9,13 +9,34 @@ import akka.stream.scaladsl.JavaConverters._
 
 trait SourceCreate {
 
+  /**
+   * Creates a `Source` by using a `FlowGraph.Builder[Unit]` on a block that expects
+   * a [[FlowGraph.Builder]] and returns an [[Outlet]].
+   */
   def create[T](block: japi.Function[FlowGraph.Builder[Unit], Outlet[T]]): Source[T, Unit] =
     new Source(scaladsl.Source() { b ⇒ block.apply(b.asJava) })
 
-  def create[T, S <: Shape, M](g1: Graph[S, M], block: japi.Function2[FlowGraph.Builder[M], S, Outlet[T]]): Source[T, M] =
+  /**
+   * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 1 graph and then returns an [[Outlet]].
+   */
+  def create[T, S <: Shape, M](g1: Graph[S, M],
+      block: japi.Function2[FlowGraph.Builder[M], S, Outlet[T]]): Source[T, M] =
     new Source(scaladsl.Source(g1) { b ⇒ s => block.apply(b.asJava, s) })
 
-  [2..21#def create[T, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  /**
+   * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 2 graphs and then returns an [[Outlet]].
+   */
+  def create[T, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
+      block: japi.Function3[FlowGraph.Builder[M], S1, S2, Outlet[T]]): Source[T, M] =
+    new Source(scaladsl.Source(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) })
+
+  [3..21#/**
+   * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 1 graphs and then returns an [[Outlet]].
+   */
+  def create1[T, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], Outlet[T]]): Source[T, M] =
     new Source(scaladsl.Source([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) })#
   
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template
index 614eec0991..5a974a5eab 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template
@@ -17,9 +17,8 @@ object ZipWith {
   def create[A, B, Out](f: japi.Function2[A, B, Out]): Graph[FanInShape2[A, B, Out], Unit] =
     scaladsl.ZipWith(f.apply _)
 
-
-  [3..20#/** Create a new `ZipWith` specialized for 1 input streams. */
-  def create[[#T1#], Out](f: japi.Function1[[#T1#], Out]): Graph[FanInShape1[[#T1#], Out], Unit] =
+  [3..20#/** Create a new `ZipWith` specialized for 1 inputs. */
+  def create1[[#T1#], Out](f: japi.Function1[[#T1#], Out]): Graph[FanInShape1[[#T1#], Out], Unit] =
     scaladsl.ZipWith(f.apply _)#
     
   ]

From d6b6220a5d1a48d1729252c42257aee233ad3eaa Mon Sep 17 00:00:00 2001
From: Konrad Malawski <konrad.malawski@typesafe.com>
Date: Thu, 9 Apr 2015 17:14:11 +0200
Subject: [PATCH 2/2] +added comments to all templates

---
 .../akka/stream/javadsl/FlexiMergeTest.java   |  1 -
 .../javadsl/BidiFlowCreate.scala.template     | 17 +++++-
 .../stream/javadsl/FlowCreate.scala.template  | 25 +++++++-
 .../stream/javadsl/GraphCreate.scala.template | 58 ++++++++++++++++++-
 .../stream/javadsl/SinkCreate.scala.template  | 15 +++--
 .../javadsl/SourceCreate.scala.template       |  6 ++
 .../stream/javadsl/ZipWith.scala.template     |  6 +-
 .../scaladsl/BidiFlowApply.scala.template     | 13 ++++-
 .../stream/scaladsl/FlowApply.scala.template  | 19 +++++-
 .../stream/scaladsl/GraphApply.scala.template | 57 +++++++++++++-----
 .../stream/scaladsl/SinkApply.scala.template  | 16 ++++-
 .../scaladsl/SourceApply.scala.template       | 18 +++++-
 .../scaladsl/ZipWithApply.scala.template      |  8 ++-
 13 files changed, 229 insertions(+), 30 deletions(-)

diff --git a/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java b/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java
index aee0acc752..33cd41f2e4 100644
--- a/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java
+++ b/akka-stream-tests/src/test/java/akka/stream/javadsl/FlexiMergeTest.java
@@ -7,7 +7,6 @@ import java.util.Arrays;
 import java.util.List;
 import java.util.HashSet;
 
-import akka.stream.javadsl.japi.Function;
 import org.junit.ClassRule;
 import org.junit.Test;
 
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template
index efabe898a7..647a88fddd 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/BidiFlowCreate.scala.template
@@ -13,18 +13,33 @@ trait BidiFlowCreate {
   import language.implicitConversions
   private implicit def p[A, B](pair: Pair[A, B]): (A, B) = pair.first -> pair.second
 
+  /**
+   * Creates a BidiFlow by applying a [[FlowGraph.Builder]] to the given create function.
+   */
   def create[I1, O1, I2, O2](block: japi.Function[FlowGraph.Builder[Unit], BidiShape[I1, O1, I2, O2]]): BidiFlow[I1, O1, I2, O2, Unit] =
     new BidiFlow(scaladsl.BidiFlow() { b ⇒ block.apply(b.asJava) })
 
+  /**
+   * Creates a BidiFlow by applying a [[FlowGraph.Builder]] to the given create function.
+   * The given graph will be imported (using `builder.graph()`) and the resulting [[Shape]] will be passed to the create function along with the builder.
+   */
   def create[I1, O1, I2, O2, S <: Shape, M](g1: Graph[S, M],
       block: japi.Function2[FlowGraph.Builder[M], S, BidiShape[I1, O1, I2, O2]]): BidiFlow[I1, O1, I2, O2, M] =
     new BidiFlow(scaladsl.BidiFlow(g1) { b ⇒ s => block.apply(b.asJava, s) })
 
+  /**
+   * Creates a BidiFlow by applying a [[FlowGraph.Builder]] to the given create function.
+   * The given graphs will be imported (using `builder.graph()`) and the resulting [[Shape]]s will be passed to the create function along with the builder.
+   */
   def create[I1, O1, I2, O2, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
       block: japi.Function3[FlowGraph.Builder[M], S1, S2, BidiShape[I1, O1, I2, O2]]): BidiFlow[I1, O1, I2, O2, M] =
     new BidiFlow(scaladsl.BidiFlow(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) })
 
-  [3..21#def create1[I##1, O##1, I##2, O##2, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  [3..21#/**
+   * Creates a BidiFlow by applying a [[FlowGraph.Builder]] to the given create function.
+   * The given graphs will be imported (using `builder.graph()`) and the resulting [[Shape]]s will be passed to the create function along with the builder.
+   */
+  def create1[I##1, O##1, I##2, O##2, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], BidiShape[I##1, O##1, I##2, O##2]]): BidiFlow[I##1, O##1, I##2, O##2, M] =
     new BidiFlow(scaladsl.BidiFlow([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) })#
   
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template
index 969287cdd3..c89dc50464 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/FlowCreate.scala.template
@@ -13,17 +13,40 @@ trait FlowCreate {
   import language.implicitConversions
   private implicit def p[A, B](pair: Pair[A, B]): (A, B) = pair.first -> pair.second
 
+  /**
+   * Creates a Flow by passing a [[FlowGraph.Builder]] to the given create function.
+   *
+   * The create function is expected to return a pair of [[Inlet]] and [[Outlet]] which correspond to the created Flows input and output ports.
+   */
   def create[I, O](block: japi.Function[FlowGraph.Builder[Unit], Inlet[I] Pair Outlet[O]]): Flow[I, O, Unit] =
     new Flow(scaladsl.Flow() { b ⇒ block.apply(b.asJava) })
 
+  /**
+   * Creates a Flow by passing a [[FlowGraph.Builder]] to the given create function.
+   * The given graph will be imported (using `builder.graph()`) and the resulting shape will be passed to the create function along with the builder.
+   *
+   * The create function is expected to return a pair of [[Inlet]] and [[Outlet]] which correspond to the created Flows input and output ports.
+   */
   def create[I, O, S <: Shape, M](g1: Graph[S, M], block: japi.Function2[FlowGraph.Builder[M], S, Inlet[I] Pair Outlet[O]]): Flow[I, O, M] =
     new Flow(scaladsl.Flow(g1) { b ⇒ s => block.apply(b.asJava, s) })
 
+  /**
+   * Creates a Flow by passing a [[FlowGraph.Builder]] to the given create function.
+   * The given graph will be imported (using `builder.graph()`) and the resulting shape will be passed to the create function along with the builder.
+   *
+   * The create function is expected to return a pair of [[Inlet]] and [[Outlet]] which correspond to the created Flows input and output ports.
+   */
   def create[I, O, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
       block: japi.Function3[FlowGraph.Builder[M], S1, S2, Inlet[I] Pair Outlet[O]]): Flow[I, O, M] =
     new Flow(scaladsl.Flow(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) })
 
-  [3..21#def create1[I, O, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  [3..21#/**
+   * Creates a Flow by passing a [[FlowGraph.Builder]] to the given create function.
+   * The given graph will be imported (using `builder.graph()`) and the resulting shape will be passed to the create function along with the builder.
+   *
+   * The create function is expected to return a pair of [[Inlet]] and [[Outlet]] which correspond to the created Flows input and output ports.
+   */
+  def create1[I, O, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], Inlet[I] Pair Outlet[O]]): Flow[I, O, M] =
     new Flow(scaladsl.Flow([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) })#
   
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template
index 56c66a30c1..2b9c92eed0 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/GraphCreate.scala.template
@@ -12,28 +12,82 @@ trait GraphCreate {
   import language.implicitConversions
   private implicit def r[M](run: scaladsl.RunnableFlow[M]): RunnableFlow[M] = new RunnableFlowAdapter(run)
 
+  /**
+   * Creates a new fully connected graph by passing a [[FlowGraph.Builder]] to the given create function.
+   *
+   * The created graph must have all ports connected, otherwise an [[IllegalArgumentException]] is thrown.
+   */
+  @throws(classOf[IllegalArgumentException])
   def closed(block: japi.Procedure[FlowGraph.Builder[Unit]]): RunnableFlow[Unit] =
     scaladsl.FlowGraph.closed() { b ⇒ block.apply(b.asJava) }
 
+  /**
+   * Creates a new [[Graph]] by passing a [[FlowGraph.Builder]] to the given create function.
+   *
+   * Partial graphs are allowed to have unconnected ports.
+   */
   def partial[S <: Shape](block: japi.Function[FlowGraph.Builder[Unit], S]): Graph[S, Unit] =
     scaladsl.FlowGraph.partial() { b ⇒ block.apply(b.asJava) }
 
+  /**
+   * Creates a new fully connected graph by importing the given graph `g1` (using `builder.graph()`) and passing its resulting [[Shape]]
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * The created graph must have all ports connected, otherwise an [[IllegalArgumentException]] is thrown.
+   */
+  @throws(classOf[IllegalArgumentException])
   def closed[S1 <: Shape, M](g1: Graph[S1, M],
       block: japi.Procedure2[FlowGraph.Builder[M], S1]): RunnableFlow[M] =
     scaladsl.FlowGraph.closed(g1) { b ⇒ s => block.apply(b.asJava, s) }
 
+  /**
+   * Creates a new [[Graph]] by importing the given graph `g1` (using `builder.graph()`) and passing its resulting [[Shape]]
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * Partial graphs are allowed to have unconnected ports.
+   */
   def partial[S1 <: Shape, S <: Shape, M](g1: Graph[S1, M],
       block: japi.Function2[FlowGraph.Builder[M], S1, S]): Graph[S, M] =
     scaladsl.FlowGraph.partial(g1) { b ⇒ s => block.apply(b.asJava, s) }
 
+  /**
+   * Creates a new fully connected graph by importing the given graphs (using `builder.graph()`) and passing their resulting [[Shape]]s
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * The created graph must have all ports connected, otherwise an [[IllegalArgumentException]] is thrown.
+   */
+  @throws(classOf[IllegalArgumentException])
   def closed[S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
       block: japi.Procedure3[FlowGraph.Builder[M], S1, S2]): RunnableFlow[M] =
     scaladsl.FlowGraph.closed(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) }
 
-  [3..21#def closed1[[#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
+  /**
+   * Creates a new [[Graph]] by importing the given graphs (using `builder.graph()`) and passing their resulting [[Shape]]s
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * Partial graphs are allowed to have unconnected ports.
+   */
+  def partial[S1 <: Shape, S2 <: Shape, S <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
+      block: japi.Function3[FlowGraph.Builder[M], S1, S2, S]): Graph[S, M] =
+    scaladsl.FlowGraph.partial(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) }
+
+  [3..21#/**
+   * Creates a new fully connected graph by importing the given graphs (using `builder.graph()`) and passing their resulting [[Shape]]s
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * The created graph must have all ports connected, otherwise an [[IllegalArgumentException]] is thrown.
+   */
+  @throws(classOf[IllegalArgumentException])
+  def closed1[[#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Procedure2[FlowGraph.Builder[M], [#S1#]]): RunnableFlow[M] =
     scaladsl.FlowGraph.closed([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) }
-    
+
+  /**
+   * Creates a new [[Graph]] by importing the given graphs (using `builder.graph()`) and passing their resulting [[Shape]]s
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * Partial graphs are allowed to have unconnected ports.
+   */
   def partial1[[#S1 <: Shape#], S <: Shape, [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], S]): Graph[S, M] =
     scaladsl.FlowGraph.partial([#g1#])(combineMat.apply _) { b => ([#s1#]) => block.apply(b.asJava, [#s1#]) }#
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
index ae1386d432..62fe374184 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
@@ -17,24 +17,27 @@ trait SinkCreate {
     new Sink(scaladsl.Sink() { b ⇒ block.apply(b.asJava) })
 
   /**
-   * Creates a `Sink` by using a `FlowGraph.Builder[M]` on a block that expects
-   * a [[FlowGraph.Builder]] and 1 graph and then returns an [[Inlet]].
+   * Creates a `Sink` by importing the given graph (using `builder.graph()`) and calling the provided create function
+   * with the `FlowGraph.Builder[M]` and the [[Shape]] resulting from importing the graph.
+   * The create function is expected to return the created Sink's [[Inlet]].
    */
   def create[T, S <: Shape, M](g1: Graph[S, M],
       block: japi.Function2[FlowGraph.Builder[M], S, Inlet[T]]): Sink[T, M] =
     new Sink(scaladsl.Sink(g1) { b ⇒ s => block.apply(b.asJava, s) })
 
   /**
-   * Creates a `Sink` by using a `FlowGraph.Builder[M]` on a block that expects
-   * a [[FlowGraph.Builder]] and 2 graphs and then returns an [[Inlet]].
+   * Creates a `Sink` by importing the given graphs (using `builder.graph()`) and calling the provided create function
+   * with the `FlowGraph.Builder[M]` and the [[Shape]]s resulting from importing the graphs.
+   * The create function is expected to return the created Sink's [[Inlet]].
    */
    def create[T, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
       block: japi.Function3[FlowGraph.Builder[M], S1, S2, Inlet[T]]): Sink[T, M] =
     new Sink(scaladsl.Sink(g1, g2)(combineMat.apply _) { b => (s1, s2) => block.apply(b.asJava, s1, s2) })
 
   [3..21#/**
-   * Creates a `Sink` by using a `FlowGraph.Builder[M]` on a block that expects
-   * a [[FlowGraph.Builder]] and 1 graphs and then returns an [[Inlet]].
+   * Creates a `Sink` by importing the given graphs (using `builder.graph()`) and calling the provided create function
+   * with the `FlowGraph.Builder[M]` and the [[Shape]]s resulting from importing the graphs.
+   * The create function is expected to return the created Sink's [[Inlet]].
    */
   def create1[T, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], Inlet[T]]): Sink[T, M] =
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template
index 1063facbc8..8b46d58099 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SourceCreate.scala.template
@@ -19,6 +19,8 @@ trait SourceCreate {
   /**
    * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
    * a [[FlowGraph.Builder]] and 1 graph and then returns an [[Outlet]].
+   * The graph will be imported (using `Builder.graph()`) and the resulting shape
+   * will be passed into the create block.
    */
   def create[T, S <: Shape, M](g1: Graph[S, M],
       block: japi.Function2[FlowGraph.Builder[M], S, Outlet[T]]): Source[T, M] =
@@ -27,6 +29,8 @@ trait SourceCreate {
   /**
    * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
    * a [[FlowGraph.Builder]] and 2 graphs and then returns an [[Outlet]].
+   * The graphs will be imported (using `Builder.graph()`) and the resulting shapes
+   * will be passed into the create block.
    */
   def create[T, S1 <: Shape, S2 <: Shape, M1, M2, M](g1: Graph[S1, M1], g2: Graph[S2, M2], combineMat: japi.Function2[M1, M2, M],
       block: japi.Function3[FlowGraph.Builder[M], S1, S2, Outlet[T]]): Source[T, M] =
@@ -35,6 +39,8 @@ trait SourceCreate {
   [3..21#/**
    * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
    * a [[FlowGraph.Builder]] and 1 graphs and then returns an [[Outlet]].
+   * The graphs will be imported (using `Builder.graph()`) and the resulting shapes
+   * will be passed into the create block.
    */
   def create1[T, [#S1 <: Shape#], [#M1#], M]([#g1: Graph[S1, M1]#], combineMat: japi.Function1[[#M1#], M],
       block: japi.Function2[FlowGraph.Builder[M], [#S1#], Outlet[T]]): Source[T, M] =
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template
index 5a974a5eab..b62e7d2b50 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/ZipWith.scala.template
@@ -17,7 +17,11 @@ object ZipWith {
   def create[A, B, Out](f: japi.Function2[A, B, Out]): Graph[FanInShape2[A, B, Out], Unit] =
     scaladsl.ZipWith(f.apply _)
 
-  [3..20#/** Create a new `ZipWith` specialized for 1 inputs. */
+  [3..20#/** Create a new `ZipWith` specialized for 1 inputs.
+   *
+   * @param f zipping-function from the input values to the output value
+   * @param attributes optional attributes for this vertex
+   */
   def create1[[#T1#], Out](f: japi.Function1[[#T1#], Out]): Graph[FanInShape1[[#T1#], Out], Unit] =
     scaladsl.ZipWith(f.apply _)#
     
diff --git a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/BidiFlowApply.scala.template b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/BidiFlowApply.scala.template
index 7321876088..8a395be009 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/BidiFlowApply.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/BidiFlowApply.scala.template
@@ -7,12 +7,19 @@ import akka.stream.{ Shape, Inlet, Outlet, Graph, BidiShape }
 
 trait BidiFlowApply {
 
+  /**
+   * Creates a BidiFlow by applying a [[FlowGraph.Builder]] to the given create block.
+   */
   def apply[I1, O1, I2, O2]()(block: FlowGraph.Builder[Unit] ⇒ BidiShape[I1, O1, I2, O2]): BidiFlow[I1, O1, I2, O2, Unit] = {
     val builder = new FlowGraph.Builder
     val shape = block(builder)
     builder.buildBidiFlow(shape)
   }
 
+  /**
+   * Creates a BidiFlow by applying a [[FlowGraph.Builder]] to the given create block.
+   * The given graph will be imported (using `builder.graph()`) and the resulting [[Shape]] will be passed to the create block along with the builder.
+   */
   def apply[I1, O1, I2, O2, Mat](g1: Graph[Shape, Mat])(buildBlock: FlowGraph.Builder[Mat] => (g1.Shape) ⇒ BidiShape[I1, O1, I2, O2]): BidiFlow[I1, O1, I2, O2, Mat] = {
     val builder = new FlowGraph.Builder
     val p = builder.add(g1, Keep.right)
@@ -20,7 +27,11 @@ trait BidiFlowApply {
     builder.buildBidiFlow(shape)
   }
   
-  [2..#def apply[I##1, O##1, I##2, O##2, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) => Mat)(
+  [2..#/**
+   * Creates a BidiFlow by applying a [[FlowGraph.Builder]] to the given create block.
+   * The given graph will be imported (using `builder.graph()`) and the resulting [[Shape]] will be passed to the create block along with the builder.
+   */
+  def apply[I##1, O##1, I##2, O##2, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) => Mat)(
     buildBlock: FlowGraph.Builder[Mat] => ([#g1.Shape#]) ⇒ BidiShape[I##1, O##1, I##2, O##2]): BidiFlow[I##1, O##1, I##2, O##2, Mat] = {
     val builder = new FlowGraph.Builder
     val curried = combineMat.curried
diff --git a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/FlowApply.scala.template b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/FlowApply.scala.template
index 29713362ed..670a7db88d 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/FlowApply.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/FlowApply.scala.template
@@ -7,12 +7,23 @@ import akka.stream.{ Shape, Inlet, Outlet, Graph }
 
 trait FlowApply {
 
+  /**
+   * Creates a Flow by passing a [[FlowGraph.Builder]] to the given create function.
+   *
+   * The create function is expected to return a pair of [[Inlet]] and [[Outlet]] which correspond to the created Flows input and output ports.
+   */
   def apply[I, O]()(block: FlowGraph.Builder[Unit] ⇒ (Inlet[I], Outlet[O])): Flow[I, O, Unit] = {
     val builder = new FlowGraph.Builder
     val (inlet, outlet) = block(builder)
     builder.buildFlow(inlet, outlet)
   }
 
+  /**
+   * Creates a Flow by passing a [[FlowGraph.Builder]] to the given create function.
+   * The given graph will be imported (using `builder.graph()`) and the resulting shape will be passed to the create function along with the builder.
+   *
+   * The create function is expected to return a pair of [[Inlet]] and [[Outlet]] which correspond to the created Flows input and output ports.
+   */
   def apply[I, O, Mat](g1: Graph[Shape, Mat])(buildBlock: FlowGraph.Builder[Mat] => (g1.Shape) ⇒ (Inlet[I], Outlet[O])): Flow[I, O, Mat] = {
     val builder = new FlowGraph.Builder
     val p = builder.add(g1, Keep.right)
@@ -20,7 +31,13 @@ trait FlowApply {
     builder.buildFlow(inlet, outlet)
   }
   
-  [2..#def apply[I, O, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) => Mat)(
+  [2..#/**
+   * Creates a Flow by passing a [[FlowGraph.Builder]] to the given create function.
+   * The given graph will be imported (using `builder.graph()`) and the resulting shape will be passed to the create function along with the builder.
+   *
+   * The create function is expected to return a pair of [[Inlet]] and [[Outlet]] which correspond to the created Flows input and output ports.
+   */
+  def apply[I, O, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) => Mat)(
     buildBlock: FlowGraph.Builder[Mat] => ([#g1.Shape#]) ⇒ (Inlet[I], Outlet[O])): Flow[I, O, Mat] = {
     val builder = new FlowGraph.Builder
     val curried = combineMat.curried
diff --git a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/GraphApply.scala.template b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/GraphApply.scala.template
index a265dea46e..8857f19abf 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/GraphApply.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/GraphApply.scala.template
@@ -8,19 +8,22 @@ import akka.stream.{ Graph, Shape }
 
 trait GraphApply {
 
+  /**
+   * Creates a new fully connected graph by passing a [[FlowGraph.Builder]] to the given create function.
+   *
+   * The created graph must have all ports connected, otherwise an [[IllegalArgumentException]] is thrown.
+   */
   def closed()(buildBlock: (FlowGraph.Builder[Unit]) ⇒ Unit): RunnableFlow[Unit] = {
     val builder = new FlowGraph.Builder
     buildBlock(builder)
     builder.buildRunnable()
   }
 
-  def closed[Mat](g1: Graph[Shape, Mat])(buildBlock: FlowGraph.Builder[Mat] ⇒ (g1.Shape) ⇒ Unit): RunnableFlow[Mat] = {
-    val builder = new FlowGraph.Builder
-    val p1 = builder.add(g1)
-    buildBlock(builder)(p1)
-    builder.buildRunnable()
-  }
-
+  /**
+   * Creates a new [[Graph]] by passing a [[FlowGraph.Builder]] to the given create function.
+   *
+   * Partial graphs are allowed to have unconnected ports.
+   */
   def partial[S <: Shape]()(buildBlock: FlowGraph.Builder[Unit] ⇒ S): Graph[S, Unit] = {
     val builder = new FlowGraph.Builder
     val s = buildBlock(builder)
@@ -32,6 +35,25 @@ trait GraphApply {
     }
   }
 
+  /**
+   * Creates a new fully connected graph by importing the given graph `g1` (using `builder.graph()`) and passing its resulting [[Shape]]
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * The created graph must have all ports connected, otherwise an [[IllegalArgumentException]] is thrown.
+   */
+  def closed[Mat](g1: Graph[Shape, Mat])(buildBlock: FlowGraph.Builder[Mat] ⇒ (g1.Shape) ⇒ Unit): RunnableFlow[Mat] = {
+    val builder = new FlowGraph.Builder
+    val p1 = builder.add(g1)
+    buildBlock(builder)(p1)
+    builder.buildRunnable()
+  }
+
+  /**
+   * Creates a new [[Graph]] by importing the given graph `g1` (using `builder.graph()`) and passing its resulting [[Shape]]
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * Partial graphs are allowed to have unconnected ports.
+   */
   def partial[S <: Shape, Mat](g1: Graph[Shape, Mat])(buildBlock: FlowGraph.Builder[Mat] ⇒ (g1.Shape) ⇒ S): Graph[S, Mat] = {
     val builder = new FlowGraph.Builder
     val s1 = builder.add(g1)
@@ -45,8 +67,13 @@ trait GraphApply {
   }
 
 
-
-  [2..#def closed[Mat, [#M1#]]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(buildBlock: FlowGraph.Builder[Mat] ⇒ ([#g1.Shape#]) ⇒ Unit): RunnableFlow[Mat] = {
+  [2..#/**
+   * Creates a new fully connected graph by importing the given graphs (using `builder.graph()`) and passing their resulting [[Shape]]s
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * The created graph must have all ports connected, otherwise an [[IllegalArgumentException]] is thrown.
+   */
+  def closed[Mat, [#M1#]]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(buildBlock: FlowGraph.Builder[Mat] ⇒ ([#g1.Shape#]) ⇒ Unit): RunnableFlow[Mat] = {
     val builder = new FlowGraph.Builder
     val curried = combineMat.curried
     val s##1 = builder.add(g##1, (_: Any, m##1: M##1) ⇒ curried(m##1))
@@ -54,11 +81,15 @@ trait GraphApply {
     ]
     buildBlock(builder)([#s1#])
     builder.buildRunnable()
-  }#
+  }
 
-  ]
-
-  [2..#def partial[S <: Shape, Mat, [#M1#]]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(buildBlock: FlowGraph.Builder[Mat] ⇒ ([#g1.Shape#]) ⇒ S): Graph[S, Mat] = {
+  /**
+   * Creates a new [[Graph]] by importing the given graphs (using `builder.graph()`) and passing their resulting [[Shape]]s
+   * along with the[[FlowGraph.Builder]] to the given create function.
+   *
+   * Partial graphs are allowed to have unconnected ports.
+   */
+  def partial[S <: Shape, Mat, [#M1#]]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(buildBlock: FlowGraph.Builder[Mat] ⇒ ([#g1.Shape#]) ⇒ S): Graph[S, Mat] = {
     val builder = new FlowGraph.Builder
     val curried = combineMat.curried
     val s##1 = builder.add(g##1, (_: Any, m##1: M##1) ⇒ curried(m##1))
diff --git a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SinkApply.scala.template b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SinkApply.scala.template
index 8e7eb0f48e..d4a289bad9 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SinkApply.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SinkApply.scala.template
@@ -7,12 +7,21 @@ import akka.stream.{ Inlet, Graph, Shape }
 
 trait SinkApply {
 
+  /**
+   * Creates a `Sink` by using a `FlowGraph.Builder[Unit]` on a block that expects
+   * a [[FlowGraph.Builder]] and returns an [[Inlet]].
+   */
   def apply[In]()(buildBlock: FlowGraph.Builder[Unit] => Inlet[In]): Sink[In, Unit] = {
     val builder = new FlowGraph.Builder
     val inlet = buildBlock(builder)
     builder.buildSink(inlet)
   }
 
+  /**
+   * Creates a `Sink` by importing the given graph (using `builder.graph()`) and calling the provided create function
+   * with the `FlowGraph.Builder[M]` and the [[Shape]] resulting from importing the graph.
+   * The create function is expected to return the created Sink's [[Inlet]].
+   */
   def apply[In, Mat](g1: Graph[Shape, Mat])(buildBlock: FlowGraph.Builder[Mat] => (g1.Shape) => Inlet[In]): Sink[In, Mat] = {
     val builder = new FlowGraph.Builder
     val s = builder.add(g1, Keep.right)
@@ -20,7 +29,12 @@ trait SinkApply {
     builder.buildSink(inlet)
   }
 
-  [2..#def apply[In, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(
+  [2..#/**
+   * Creates a `Sink` by importing the given graphs (using `builder.graph()`) and calling the provided create function
+   * with the `FlowGraph.Builder[M]` and the [[Shape]]s resulting from importing the graphs.
+   * The create function is expected to return the created Sink's [[Inlet]].
+   */
+  def apply[In, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(
     buildBlock: FlowGraph.Builder[Mat] ⇒ ([#g1.Shape#]) ⇒ Inlet[In]): Sink[In, Mat] = {
     val builder = new FlowGraph.Builder
     val curried = combineMat.curried
diff --git a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SourceApply.scala.template b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SourceApply.scala.template
index b2c3c1c7f1..93190c0582 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SourceApply.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/SourceApply.scala.template
@@ -7,12 +7,22 @@ import akka.stream.{ Outlet, Shape, Graph }
 
 trait SourceApply {
 
+  /**
+   * Creates a `Source` by using a `FlowGraph.Builder[Unit]` on a block that expects
+   * a [[FlowGraph.Builder]] and returns an [[Outlet]].
+   */
   def apply[Out]()(buildBlock: FlowGraph.Builder[Unit] => Outlet[Out]): Source[Out, Unit] = {
     val builder = new FlowGraph.Builder
     val port = buildBlock(builder)
     builder.buildSource(port)
   }
 
+  /**
+   * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 1 graph and then returns an [[Outlet]].
+   * The graph will be imported (using `Builder.graph()`) and the resulting shape
+   * will be passed into the create block.
+   */
   def apply[Out, Mat](g1: Graph[Shape, Mat])(buildBlock: FlowGraph.Builder[Mat] => (g1.Shape) => Outlet[Out]): Source[Out, Mat] = {
     val builder = new FlowGraph.Builder
     val p = builder.add(g1, Keep.right)
@@ -20,7 +30,13 @@ trait SourceApply {
     builder.buildSource(port)
   }
 
-  [2..#def apply[Out, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(
+  [2..#/**
+   * Creates a `Source` by using a `FlowGraph.Builder[M]` on a block that expects
+   * a [[FlowGraph.Builder]] and 2 graphs and then returns an [[Outlet]].
+   * The graphs will be imported (using `Builder.graph()`) and the resulting shapes
+   * will be passed into the create block.
+   */
+  def apply[Out, [#M1#], Mat]([#g1: Graph[Shape, M1]#])(combineMat: ([#M1#]) ⇒ Mat)(
     buildBlock: FlowGraph.Builder[Mat] ⇒ ([#g1.Shape#]) ⇒ Outlet[Out]): Source[Out, Mat] = {
     val builder = new FlowGraph.Builder
     val curried = combineMat.curried
diff --git a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/ZipWithApply.scala.template b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/ZipWithApply.scala.template
index 0980b54267..547a5c2ff5 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/scaladsl/ZipWithApply.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/scaladsl/ZipWithApply.scala.template
@@ -8,7 +8,13 @@ import akka.stream._
 
 trait ZipWithApply {
 
-  [2..20#def apply[[#A1#], O](zipper: ([#A1#]) ⇒ O): Graph[FanInShape1[[#A1#], O], Unit] =
+  [2..20#/**
+   * Create a new `ZipWith` specialized for 1 inputs.
+   *
+   * @param f zipping-function from the input values to the output value
+   * @param attributes optional attributes for this vertex
+   */
+  def apply[[#A1#], O](zipper: ([#A1#]) ⇒ O): Graph[FanInShape1[[#A1#], O], Unit] =
     new Graph[FanInShape1[[#A1#], O], Unit] {
       val shape = new FanInShape1[[#A1#], O]("ZipWith1")
       val module = new ZipWith1Module(shape, zipper, OperationAttributes.name("ZipWith1"))