IO Handles: update comments [skip ci]

* hSetEcho, hGetEcho and hIsTerminalDevice are part of the Haskell2010
report (but not Haskell98)

* there are great `Note`s in GHC.IO.Handle.Types. Link to them.

libraries/base/GHC/IO/Handle.hs

@@ -508,7 +508,7 @@ hIsSeekable handle =
       _                    -> IODevice.isSeekable haDevice
 
 -- -----------------------------------------------------------------------------
--- Changing echo status (Non-standard GHC extensions)
+-- Changing echo status
 
 -- | Set the echoing status of a handle connected to a terminal.
 

libraries/base/GHC/IO/Handle/Internals.hs

@@ -480,15 +480,19 @@ flushCharBuffer h_@Handle__{..} = do
     ReadBuffer  -> do
         flushCharReadBuffer h_
     WriteBuffer ->
+        -- Nothing to do here. Char buffer on a write Handle is always empty
+        -- between Handle operations.
+        -- See [note Buffer Flushing], GHC.IO.Handle.Types.
         when (not (isEmptyBuffer cbuf)) $
            error "internal IO library error: Char buffer non-empty"
 
 -- -----------------------------------------------------------------------------
 -- Writing data (flushing write buffers)
 
--- flushWriteBuffer flushes the buffer iff it contains pending write
--- data.  Flushes both the Char and the byte buffer, leaving both
--- empty.
+-- flushWriteBuffer flushes the byte buffer iff it contains pending write
+-- data. Because the Char buffer on a write Handle is always empty between
+-- Handle operations (see [note Buffer Flushing], GHC.IO.Handle.Types),
+-- both buffers are empty after this.
 flushWriteBuffer :: Handle__ -> IO ()
 flushWriteBuffer h_@Handle__{..} = do
   buf <- readIORef haByteBuffer
@@ -519,7 +523,7 @@ writeCharBuffer h_@Handle__{..} !cbuf = do
   debugIO ("writeCharBuffer after encoding: cbuf=" ++ summaryBuffer cbuf' ++
         " bbuf=" ++ summaryBuffer bbuf')
 
-          -- flush if the write buffer is full
+          -- flush the byte buffer if it is full
   if isFullBuffer bbuf'
           --  or we made no progress
      || not (isEmptyBuffer cbuf') && bufL cbuf' == bufL cbuf

libraries/base/GHC/IO/Handle/Types.hs

@@ -122,10 +122,10 @@ data Handle__
     Handle__ {
       haDevice      :: !dev,
       haType        :: HandleType,           -- type (read/write/append etc.)
-      haByteBuffer  :: !(IORef (Buffer Word8)),
+      haByteBuffer  :: !(IORef (Buffer Word8)), -- See [note Buffering Implementation]
       haBufferMode  :: BufferMode,
       haLastDecode  :: !(IORef (dec_state, Buffer Word8)),
-      haCharBuffer  :: !(IORef (Buffer CharBufElem)), -- the current buffer
+      haCharBuffer  :: !(IORef (Buffer CharBufElem)), -- See [note Buffering Implementation]
       haBuffers     :: !(IORef (BufferList CharBufElem)),  -- spare buffers
       haEncoder     :: Maybe (TextEncoder enc_state),
       haDecoder     :: Maybe (TextDecoder dec_state),