Add and reuse example for FileIO stream operator. (#25660)

akka-docs/src/main/paradox/stream/operators/FileIO/fromFile.md

@@ -0,0 +1,25 @@
+# FileIO.fromFile
+
+Emits the contents of a file.
+
+@ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources)
+
+@@@ warning
+
+The `fromFile` operator has been deprecated, use @ref:[fromPath](./fromPath.md) instead. 
+
+@@@
+
+@@@div { .group-scala }
+
+## Signature
+
+@@signature [FileIO.scala](/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala) { #fromFile }
+
+@@@
+
+## Description
+
+Emits the contents of a file, as `ByteString`s, materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with
+a `IOResult` upon reaching the end of the file or if there is a failure.
+

akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md

@@ -1,6 +1,6 @@
 # FileIO.fromPath
 
-Emit the contents of a file.
+Emits the contents of a file from the given path.
 
 @ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources)
 
@@ -14,5 +14,14 @@ Emit the contents of a file.
 
 ## Description
 
-Emit the contents of a file, as `ByteString`s, materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with
+Emits the contents of a file from the given path, as `ByteString`s, materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with
 a `IOResult` upon reaching the end of the file or if there is a failure.
+
+## Example
+
+Scala
+:  @@snip [StreamFileDocSpec.scala](/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala) { #file-source }
+
+Java
+:  @@snip [StreamFileDocTest.java](/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java) { #file-source }
+

akka-docs/src/main/paradox/stream/operators/FileIO/toFile.md

@@ -0,0 +1,24 @@
+# FileIO.toFile
+
+Create a sink which will write incoming `ByteString` s to a given file.
+
+@ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources)
+
+@@@ warning
+
+The `toFile` operator has been deprecated, use @ref:[toPath](./toPath.md) instead. 
+
+@@@
+
+@@@div { .group-scala }
+
+## Signature
+
+@@signature [FileIO.scala](/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala) { #toFile }
+
+@@@
+
+## Description
+
+Creates a Sink which writes incoming `ByteString` elements to the given file path. Overwrites existing files by truncating their contents as default. 
+Materializes a @scala[`Future`] @java[`CompletionStage`] of `IOResult` that will be completed with the size of the file (in bytes) at the streams completion, and a possible exception if IO operation was not completed successfully.

akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md

@@ -14,4 +14,13 @@ Create a sink which will write incoming `ByteString` s to a given file path.
 
 ## Description
 
-TODO: We would welcome help on contributing descriptions and examples, see: https://github.com/akka/akka/issues/25646
+Creates a Sink which writes incoming `ByteString` elements to the given file path. Overwrites existing files by truncating their contents as default. 
+Materializes a @scala[`Future`] @java[`CompletionStage`] of `IOResult` that will be completed with the size of the file (in bytes) at the streams completion, and a possible exception if IO operation was not completed successfully.
+
+## Example
+
+Scala
+:  @@snip [StreamFileDocSpec.scala](/akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala) { #file-sink }
+
+Java
+:  @@snip [StreamFileDocTest.java](/akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java) { #file-sink }

akka-docs/src/main/paradox/stream/operators/index.md

@@ -106,7 +106,9 @@ Sources and sinks for reading and writing files can be found on `FileIO`.
 
 | |Operator|Description|
 |--|--|--|
-|FileIO|<a name="frompath"></a>@ref[fromPath](FileIO/fromPath.md)|Emit the contents of a file.|
+|FileIO|<a name="fromfile"></a>@ref[fromFile](FileIO/fromFile.md)|Emits the contents of a file.|
+|FileIO|<a name="frompath"></a>@ref[fromPath](FileIO/fromPath.md)|Emits the contents of a file from the given path.|
+|FileIO|<a name="tofile"></a>@ref[toFile](FileIO/toFile.md)|Create a sink which will write incoming `ByteString` s to a given file.|
 |FileIO|<a name="topath"></a>@ref[toPath](FileIO/toPath.md)|Create a sink which will write incoming `ByteString` s to a given file path.|
 
 ## Simple operators
@@ -397,7 +399,9 @@ Operators meant for inter-operating between Akka Streams and Actors:
 * [javaCollectorParallelUnordered](StreamConverters/javaCollectorParallelUnordered.md)
 * [asJavaStream](StreamConverters/asJavaStream.md)
 * [fromJavaStream](StreamConverters/fromJavaStream.md)
+* [fromFile](FileIO/fromFile.md)
 * [fromPath](FileIO/fromPath.md)
+* [toFile](FileIO/toFile.md)
 * [toPath](FileIO/toPath.md)
 * [ask](ActorFlow/ask.md)
 * [actorRef](ActorSink/actorRef.md)

akka-docs/src/test/java/jdocs/stream/io/StreamFileDocTest.java

@@ -11,10 +11,12 @@ import java.io.IOException;
 import java.util.concurrent.CompletionStage;
 
 import akka.Done;
+import akka.NotUsed;
 import akka.actor.ActorSystem;
 import akka.stream.ActorAttributes;
 import akka.stream.javadsl.Sink;
 import akka.stream.javadsl.FileIO;
+import akka.stream.javadsl.Source;
 import jdocs.AbstractJavaTest;
 import jdocs.stream.SilenceSystemOut;
 import akka.testkit.javadsl.TestKit;
@@ -48,9 +50,16 @@ public class StreamFileDocTest extends AbstractJavaTest {
   final SilenceSystemOut.System System = SilenceSystemOut.get();
 
   {
-    //#file-source
-    final Path file = Paths.get("example.csv");
-    //#file-source
+      // Using 4 spaces here to align with code in try block below.
+      //#file-source
+      final Path file = Paths.get("example.csv");
+      //#file-source
+  }
+
+  {
+      //#file-sink
+      final Path file = Paths.get("greeting.txt");
+      //#file-sink
   }
 
   @Test
@@ -87,5 +96,21 @@ public class StreamFileDocTest extends AbstractJavaTest {
     }
   }
 
+  @Test
+  public void demontrateFileIOWriting() throws IOException {
+    final Path file = Files.createTempFile(getClass().getName(), ".tmp");
 
+    try {
+      //#file-sink
+      Sink<ByteString, CompletionStage<IOResult>> fileSink = FileIO.toPath(file);
+      Source<String, NotUsed> textSource = Source.single("Hello Akka Stream!");
+
+      CompletionStage<IOResult> ioResult = textSource
+        .map(ByteString::fromString)
+        .runWith(fileSink, mat);
+      //#file-sink
+    } finally {
+      Files.delete(file);
+    }
+  }
 }

akka-docs/src/test/scala/docs/stream/io/StreamFileDocSpec.scala

@@ -7,7 +7,7 @@ package docs.stream.io
 import java.nio.file.{ Files, Paths }
 
 import akka.stream._
-import akka.stream.scaladsl.{ FileIO, Sink }
+import akka.stream.scaladsl.{ FileIO, Sink, Source }
 import akka.stream.testkit.Utils._
 import akka.util.ByteString
 import akka.testkit.AkkaSpec
@@ -39,6 +39,12 @@ class StreamFileDocSpec extends AkkaSpec(UnboundedMailboxConfig) {
     //#file-source
   }
 
+  {
+    //#file-sink
+    val file = Paths.get("greeting.txt")
+    //#file-sink
+  }
+
   "read data from a file" in {
     //#file-source
     def handle(b: ByteString): Unit //#file-source
@@ -58,4 +64,13 @@ class StreamFileDocSpec extends AkkaSpec(UnboundedMailboxConfig) {
       .withAttributes(ActorAttributes.dispatcher("custom-blocking-io-dispatcher"))
     //#custom-dispatcher-code
   }
+
+  "write data into a file" in {
+    //#file-sink
+    val text = Source.single("Hello Akka Stream!")
+    val result: Future[IOResult] = text
+      .map(t ⇒ ByteString(t))
+      .runWith(FileIO.toPath(file))
+    //#file-sink
+  }
 }

akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala

@@ -63,7 +63,7 @@ object FileIO {
    * except the final element, which will be up to `chunkSize` in size.
    *
    * You can configure the default dispatcher for this Source by changing the `akka.stream.materializer.blocking-io-dispatcher` or
-   * set it for a given Source by using [[ActorAttributes]].
+   * set it for a given Source by using [[akka.stream.ActorAttributes]].
    *
    * It materializes a [[Future]] of [[IOResult]] containing the number of bytes read from the source file upon completion,
    * and a possible exception if IO operation was not completed successfully.
@@ -122,7 +122,7 @@ object FileIO {
    * and a possible exception if IO operation was not completed successfully.
    *
    * This source is backed by an Actor which will use the dedicated `akka.stream.blocking-io-dispatcher`,
-   * unless configured otherwise by using [[ActorAttributes]].
+   * unless configured otherwise by using [[akka.stream.ActorAttributes]].
    *
    * Accepts as arguments a set of [[java.nio.file.StandardOpenOption]], which will determine
    * the underlying behavior when writing the file. If [[java.nio.file.StandardOpenOption.SYNC]] is

project/StreamOperatorsIndexGenerator.scala

@@ -106,10 +106,6 @@ object StreamOperatorsIndexGenerator extends AutoPlugin {
       "foldAsync",
       "newOnCompleteStage"
     ),
-    "FileIO" -> Seq(
-      "fromFile",
-      "toFile"
-    ),
     "ActorSink" → Seq(
       "actorRefWithAck"
     ),