Improve byChunk, lockingTextWriter doc

Make byChunk, lockingTextWriter return opaque types (but keep those
types public for backward compatibility).
Add byChunk range example.
Also document that ByLine's primitives can throw StdioException.

std/stdio.d

@@ -1124,7 +1124,8 @@ Allows to directly use range operations on lines of a file.
 Returns an input range set up to read from the file handle one line 
 at a time.
 
-The element type for the range will be $(D Char[]).
+The element type for the range will be $(D Char[]). Range primitives 
+may throw $(D StdioException) on I/O error.
 
 Params:
 Char = Character type for each line, defaulting to $(D char). If 
@@ -1254,7 +1255,7 @@ void main()
     }
 
 
-    /**
+    /*
      * Range that reads a chunk at a time.
      */
     struct ByChunk
@@ -1308,10 +1309,17 @@ void main()
     }
 
 /**
-Iterates through a file a chunk at a time by using $(D foreach).
+Returns an input range set up to read from the file handle a chunk at a 
+time.
 
-Example:
+The element type for the range will be $(D ubyte[]). Range primitives 
+may throw $(D StdioException) on I/O error.
 
+Note: Each $(D front) will not persist after $(D 
+popFront) is called, so the caller must copy its contents (e.g. by 
+calling $(D buffer.dup)) if retention is needed.
+
+Example:
 ---------
 void main()
 {
@@ -1321,15 +1329,22 @@ void main()
   }
 }
 ---------
-
 The content of $(D buffer) is reused across calls. In the example
 above, $(D buffer.length) is 4096 for all iterations, except for the
 last one, in which case $(D buffer.length) may be less than 4096 (but
 always greater than zero).
 
-In case of an I/O error, an $(D StdioException) is thrown.
+Example:
+---
+import std.algorithm, std.stdio;
+
+void main()
+{
+    stdin.byChunk(1024).copy(stdout.lockingTextWriter());
+}
+---
  */
-    ByChunk byChunk(size_t chunkSize)
+    auto byChunk(size_t chunkSize)
     {
         return ByChunk(this, chunkSize);
     }
@@ -1357,7 +1372,7 @@ In case of an I/O error, an $(D StdioException) is thrown.
         assert(i == witness.length);
     }
 
-/**
+/*
 $(D Range) that locks the file and allows fast writing to it.
  */
     struct LockingTextWriter
@@ -1491,8 +1506,11 @@ $(D Range) that locks the file and allows fast writing to it.
         }
     }
 
-/// Convenience function.
-    @property LockingTextWriter lockingTextWriter()
+/** Returns an output range that locks the file and allows fast writing to it.
+
+See $(LREF byChunk) for an example.
+*/
+    @property auto lockingTextWriter()
     {
         return LockingTextWriter(this);
     }