Update console module docs

Author: harendra-kumar

core/src/Streamly/Console/Stdio.hs

@@ -7,10 +7,25 @@
 -- Stability   : released
 -- Portability : GHC
 --
--- Combinators to work with standard input, output and error streams.
+-- Combinators to work with standard input, output, and error streams. This
+-- module supports reading and writing binary data or UTF-8 encoded text only.
+-- However, it is possible to use specific encoders and decoders to implement
+-- other encodings.
+--
+-- These streaming APIs use the stdin and stdout handles for reading from and
+-- writing to the console. The reads and writes are buffered, meaning each
+-- stream has its own buffer. Be cautious when switching between these APIs and
+-- handle-based APIs (e.g., readChars, getLine), between different stream APIs
+-- (e.g., readChars, readChunks), or even between different calls to the same
+-- API (e.g., readChars, readChars). If you switch from one stream to another,
+-- you should drain the first stream completely if you care about preserving
+-- any buffered data.
 --
 -- See also: "Streamly.Internal.Console.Stdio"
 
+-- XXX put examples of repeatM getLine from stream module
+-- XXX put examples of using parseBreak or foldBreak.
+
 module Streamly.Console.Stdio
     (
     -- * Streams (stdin)

core/src/Streamly/Internal/Console/Stdio.hs

@@ -9,15 +9,24 @@
 
 module Streamly.Internal.Console.Stdio
     (
-    -- * Streams
+    -- * Singleton APIs
+      -- getChunk
+    -- , putChunk
+
+    -- * Stream reads
       read
-    , readChars
+    -- , readWith -- buffer
     , readChunks
-    -- , getChunksLn
-    -- , getStringsWith -- get strings using the supplied decoding
-    -- , getStrings -- get strings of complete chars,
-                  -- leave any partial chars for next string
-    -- , getStringsLn -- get lines decoded as char strings
+    -- , readChunksWith -- buffer
+    -- , readChunksLn -- chunks with line buffering -- repeatM Text.getLine
+
+    -- -- ** Encoding specific
+    -- , readCharsWith
+    -- , readStringsLnWith
+
+    -- ** UTF-8 decoded
+    , readChars
+    -- , readStringsLn -- strings with line buffering -- repeatM getLine
 
     -- * Unfolds
     , reader
@@ -31,11 +40,18 @@ module Streamly.Internal.Console.Stdio
 
     -- * Stream writes
     , putBytes  -- Buffered (32K)
-    , putChars
     , putChunks -- Unbuffered
+
+    -- ** Encoding specific
+    -- , putCharsWith
     , putStringsWith
+    -- , putStringsLnWith
+
+    -- ** UTF-8 encoded
+    , putChars
     , putStrings
     , putStringsLn
+    -- , putChunksLn
     )
 where
 
@@ -193,7 +209,7 @@ putChunks = Handle.putChunks stdout
 -- folds as well as unfolds/streams. Non-backtracking (one-to-one, one-to-many,
 -- filters, reducers) transformations may be easy so we can possibly start with
 -- those.
---
+
 -- | Write a stream of strings to standard output using the supplied encoding.
 -- Output is flushed to the device for each string.
 --