Improve docs

Author: hdgarrood

src/Node/Stream.purs

@@ -58,7 +58,11 @@ type Duplex = Stream (read :: Read, write :: Write)
 
 foreign import setEncodingImpl :: forall w eff. Readable w eff -> String -> Eff eff Unit
 
--- | Set the encoding used to read chunks as strings from the stream.
+-- | Set the encoding used to read chunks as strings from the stream. This
+-- | function is useful when you are passing a readable stream to some other
+-- | JavaScript library, which already expects an encoding to be set. It
+-- | has no effect on the behaviour of the `onDataString` function (because
+-- | that function ensures that the encoding is always supplied explicitly).
 setEncoding :: forall w eff. Readable w eff -> Encoding -> Eff eff Unit
 setEncoding r enc = setEncodingImpl r (show enc)
 
@@ -68,8 +72,8 @@ foreign import onDataImpl :: forall w eff a. Readable w eff -> (a -> Eff eff Uni
 onData :: forall w eff. Readable w eff -> (Buffer -> Eff eff Unit) -> Eff eff Unit
 onData = onDataImpl
 
--- | Listen for `data` events, returning data in a String, decoded with the
--- | given encoding.
+-- | Listen for `data` events, returning data in a String, which will be
+-- | decoded using the given encoding.
 onDataString :: forall w eff. Readable w eff -> Encoding -> (String -> Eff eff Unit) -> Eff eff Unit
 onDataString r enc cb = onData r $ \buf -> do
   str <- unsafeInterleaveEff (Buffer.toString enc buf)
@@ -113,7 +117,11 @@ foreign import uncork :: forall r eff. Writable r eff -> Eff eff Unit
 
 foreign import setDefaultEncodingImpl :: forall r eff. Writable r eff -> String -> Eff eff Unit
 
--- | Set the default encoding used to write chunks to the stream. This
+-- | Set the default encoding used to write chunks to the stream. This function
+-- | is useful when you are passing a writable stream to some other JavaScript
+-- | library, which already expects a default encoding to be set. It has no
+-- | effect on the behaviour of the `writeString` function (because that
+-- | function ensures that the encoding is always supplied explicitly).
 setDefaultEncoding :: forall r eff. Writable r eff -> Encoding -> Eff eff Unit
 setDefaultEncoding r enc = setDefaultEncodingImpl r (show enc)