[commit: bytestring] master: A few minor doc improvements (0074e5f)

[Ian Lynagh]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/bytestring

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/0074e5f12f4ec5620b300cfeec5aef3119316cc4

>---------------------------------------------------------------

commit 0074e5f12f4ec5620b300cfeec5aef3119316cc4
Author: Duncan Coutts <duncan at community.haskell.org>
Date:   Mon Nov 7 11:35:55 2011 +0000

    A few minor doc improvements

>---------------------------------------------------------------

 Data/ByteString/Char8.hs      |    6 +++---
 Data/ByteString/Internal.hs   |    2 +-
 Data/ByteString/Lazy.hs       |   21 +++++++++++----------
 Data/ByteString/Lazy/Char8.hs |    5 +++++
 4 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/Data/ByteString/Char8.hs b/Data/ByteString/Char8.hs
index 47704e4..d13d033 100644
--- a/Data/ByteString/Char8.hs
+++ b/Data/ByteString/Char8.hs
@@ -35,12 +35,12 @@
 -- This module is intended to be imported @qualified@, to avoid name
 -- clashes with "Prelude" functions.  eg.
 --
--- > import qualified Data.ByteString.Char8 as B
+-- > import qualified Data.ByteString.Char8 as C
 --
 -- The Char8 interface to bytestrings provides an instance of IsString
 -- for the ByteString type, enabling you to use string literals, and
--- have them implicitly packed to ByteStrings. Use -XOverloadedStrings
--- to enable this.
+-- have them implicitly packed to ByteStrings.
+-- Use @{-\# LANGUAGE OverloadedStrings \#-}@ to enable this.
 --
 
 module Data.ByteString.Char8 (
diff --git a/Data/ByteString/Internal.hs b/Data/ByteString/Internal.hs
index bd51d2e..0552f1d 100644
--- a/Data/ByteString/Internal.hs
+++ b/Data/ByteString/Internal.hs
@@ -31,7 +31,7 @@ module Data.ByteString.Internal (
         unpackBytes, unpackAppendBytesLazy, unpackAppendBytesStrict,
         unpackChars, unpackAppendCharsLazy, unpackAppendCharsStrict,
 
-        -- * Low level introduction and elimination
+        -- * Low level imperative construction
         create,                 -- :: Int -> (Ptr Word8 -> IO ()) -> IO ByteString
         createAndTrim,          -- :: Int -> (Ptr Word8 -> IO Int) -> IO  ByteString
         createAndTrim',         -- :: Int -> (Ptr Word8 -> IO (Int, Int, a)) -> IO (ByteString, a)
diff --git a/Data/ByteString/Lazy.hs b/Data/ByteString/Lazy.hs
index a97257a..ab87a7d 100644
--- a/Data/ByteString/Lazy.hs
+++ b/Data/ByteString/Lazy.hs
@@ -18,19 +18,20 @@
 -- A time and space-efficient implementation of lazy byte vectors
 -- using lists of packed 'Word8' arrays, suitable for high performance
 -- use, both in terms of large data quantities, or high speed
--- requirements. Byte vectors are encoded as lazy lists of strict 'Word8'
--- arrays of bytes. They provide a means to manipulate large byte vectors
--- without requiring the entire vector be resident in memory.
+-- requirements. Lazy ByteStrings are encoded as lazy lists of strict chunks
+-- of bytes.
 --
--- Some operations, such as concat, append, reverse and cons, have
+-- A key feature of lazy ByteStrings is the means to manipulate large or
+-- unbounded streams of data without requiring the entire sequence to be
+-- resident in memory. To take advantage of this you have to write your
+-- functions in a lazy streaming style, e.g. classic pipeline composition. The
+-- default I\/O chunk size is 32k, which should be good in most circumstances.
+--
+-- Some operations, such as 'concat', 'append', 'reverse' and 'cons', have
 -- better complexity than their "Data.ByteString" equivalents, due to
--- optimisations resulting from the list spine structure. And for other
+-- optimisations resulting from the list spine structure. For other
 -- operations lazy ByteStrings are usually within a few percent of
--- strict ones, but with better heap usage. For data larger than the
--- available memory, or if you have tight memory constraints, this
--- module will be the only option. The default chunk size is 64k, which
--- should be good in most circumstances. For people with large L2
--- caches, you may want to increase this to fit your cache.
+-- strict ones.
 --
 -- This module is intended to be imported @qualified@, to avoid name
 -- clashes with "Prelude" functions.  eg.
diff --git a/Data/ByteString/Lazy/Char8.hs b/Data/ByteString/Lazy/Char8.hs
index 51d9b47..bd4b3a0 100644
--- a/Data/ByteString/Lazy/Char8.hs
+++ b/Data/ByteString/Lazy/Char8.hs
@@ -23,6 +23,11 @@
 --
 -- > import qualified Data.ByteString.Lazy.Char8 as C
 --
+-- The Char8 interface to bytestrings provides an instance of IsString
+-- for the ByteString type, enabling you to use string literals, and
+-- have them implicitly packed to ByteStrings.
+-- Use @{-\# LANGUAGE OverloadedStrings \#-}@ to enable this.
+--
 
 module Data.ByteString.Lazy.Char8 (