Fix Issue 18648 - Document the type of std.stdio.stdin and friends

std/experimental/all.d

@@ -10,8 +10,8 @@ module std.experimental.all;
 
     int len;
     const r = 6.iota
-              .filter!(a => a % 2) // 0 2 4
-              .map!(a => a * 2) // 0 4 8
+              .filter!(a => a % 2) // 1 3 5
+              .map!(a => a * 2) // 2 6 10
               .tee!(_ => len++)
               .sum
               .reverseArgs!format("Sum: %d");

std/stdio.d

@@ -4689,6 +4689,8 @@ enum StdFileHandle: string
         Due to $(LINK2 https://issues.dlang.org/show_bug.cgi?id=15768, bug 15768),
         it is thread un-safe to reassign `stdin` to a different `File` instance
         than the default.
+
+    Returns: stdin as $(LREF File).
 */
 alias stdin = makeGlobal!(StdFileHandle.stdin);
 
@@ -4717,18 +4719,75 @@ alias stdin = makeGlobal!(StdFileHandle.stdin);
         Due to $(LINK2 https://issues.dlang.org/show_bug.cgi?id=15768, bug 15768),
         it is thread un-safe to reassign `stdout` to a different `File` instance
         than the default.
+
+    Returns: stdin as $(LREF File).
 */
 alias stdout = makeGlobal!(StdFileHandle.stdout);
 
+///
+@safe unittest
+{
+    void main()
+    {
+        stdout.writeln("Write a message to stdout.");
+    }
+}
+
+///
+@safe unittest
+{
+    void main()
+    {
+        import std.algorithm.iteration : filter, map, sum;
+        import std.format : format;
+        import std.range : iota, tee;
+
+        int len;
+        const r = 6.iota
+                  .filter!(a => a % 2) // 1 3 5
+                  .map!(a => a * 2) // 2 6 10
+                  .tee!(_ => stdout.writefln("len: %d", len++))
+                  .sum;
+
+        assert(r == 18);
+    }
+}
+
+///
+@safe unittest
+{
+    void main() {
+        import std.algorithm.mutation : copy;
+        import std.algorithm.iteration : map;
+        import std.format : format;
+        import std.range : iota;
+
+        10.iota
+        .map!(e => "N: %d".format(e))
+        .copy(stdout.lockingTextWriter()); // the OutputRange
+    }
+}
+
 /**
     The standard error stream.
     Bugs:
         Due to $(LINK2 https://issues.dlang.org/show_bug.cgi?id=15768, bug 15768),
         it is thread un-safe to reassign `stderr` to a different `File` instance
         than the default.
+
+    Returns: stdin as $(LREF File).
 */
 alias stderr = makeGlobal!(StdFileHandle.stderr);
 
+///
+@safe unittest
+{
+    void main()
+    {
+        stderr.writeln("Write a message to stderr.");
+    }
+}
+
 @system unittest
 {
     static import std.file;