Improve haddocks of top-level modules (#127)

src/Network/Minio.hs

@@ -20,13 +20,17 @@
 -- License:     Apache 2.0
 -- Maintainer:  MinIO Dev Team <dev@min.io>
 --
--- Types and functions to access S3 compatible object storage servers
--- like MinIO.
+-- Types and functions to conveniently access S3 compatible object
+-- storage servers like MinIO.
 
 module Network.Minio
   (
   -- * Credentials
     Credentials (..)
+
+  -- ** Credential providers
+  -- | Run actions that retrieve 'Credentials' from the environment or
+  -- files or other custom sources.
   , Provider
   , fromAWSConfigFile
   , fromAWSEnv
@@ -34,7 +38,6 @@ module Network.Minio
   , findFirst
 
   -- * Connecting to object storage
-  ---------------------------------
   , ConnectInfo
   , setRegion
   , setCreds
@@ -45,26 +48,23 @@ module Network.Minio
   , mkMinioConn
 
   -- ** Connection helpers
-  ------------------------
+  -- | These are helpers to construct 'ConnectInfo' values for common
+  -- cases.
   , minioPlayCI
   , awsCI
   , gcsCI
 
-
   -- * Minio Monad
   ----------------
   -- | The Minio Monad provides connection-reuse, bucket-location
   -- caching, resource management and simpler error handling
   -- functionality. All actions on object storage are performed within
   -- this Monad.
-
   , Minio
   , runMinioWith
   , runMinio
 
-
   -- * Bucket Operations
-  ----------------------
 
   -- ** Creation, removal and querying
   , Bucket
@@ -74,11 +74,15 @@ module Network.Minio
   , Region
   , getLocation
 
-  -- ** Listing
+  -- ** Listing buckets
   , BucketInfo(..)
   , listBuckets
 
-  -- ** Object info type represents object metadata information.
+  -- ** Listing objects
+  , listObjects
+  , listObjectsV1
+  , ListItem(..)
+
   , ObjectInfo
   , oiObject
   , oiModTime
@@ -86,17 +90,17 @@ module Network.Minio
   , oiSize
   , oiMetadata
 
-  , ListItem(..)
-  , listObjects
-  , listObjectsV1
-
+  -- ** Listing incomplete uploads
+  , listIncompleteUploads
   , UploadId
   , UploadInfo(..)
-  , listIncompleteUploads
-  , ObjectPartInfo(..)
   , listIncompleteParts
+  , ObjectPartInfo(..)
 
   -- ** Bucket Notifications
+  , getBucketNotification
+  , putBucketNotification
+  , removeAllBucketNotification
   , Notification(..)
   , defaultNotification
   , NotificationConfig(..)
@@ -109,15 +113,11 @@ module Network.Minio
   , FilterRules(..)
   , defaultFilterRules
   , FilterRule(..)
-  , getBucketNotification
-  , putBucketNotification
-  , removeAllBucketNotification
 
   -- * Object Operations
-  ----------------------
   , Object
 
-  -- ** File operations
+  -- ** File-based operations
   , fGetObject
   , fPutObject
 
@@ -145,7 +145,7 @@ module Network.Minio
   , gooIfUnmodifiedSince
   , gooSSECKey
 
-  -- ** Server-side copying
+  -- ** Server-side object copying
   , copyObject
   , SourceInfo
   , defaultSourceInfo
@@ -161,38 +161,38 @@ module Network.Minio
   , dstBucket
   , dstObject
 
-  -- ** Querying
+  -- ** Querying object info
   , statObject
 
-  -- ** Object removal functions
+  -- ** Object removal operations
   , removeObject
   , removeIncompleteUpload
 
   -- ** Select Object Content with SQL
   , module Network.Minio.SelectAPI
 
-  -- * Server-Size Encryption Helpers
-  -----------------------------------
-  , SSECKey
+  -- * Server-Side Encryption Helpers
   , mkSSECKey
+  , SSECKey
   , SSE(..)
 
-
   -- * Presigned Operations
-  -------------------------
-  , UrlExpiry
   , presignedPutObjectUrl
   , presignedGetObjectUrl
   , presignedHeadObjectUrl
+  , UrlExpiry
 
-  -- ** Utilities for POST (browser) uploads
-  , PostPolicy
-  , PostPolicyError(..)
+  -- ** POST (browser) upload helpers
+  -- | Please see
+  -- https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTConstructPolicy.html
+  -- for detailed information.
   , newPostPolicy
   , presignedPostPolicy
   , showPostPolicy
+  , PostPolicy
+  , PostPolicyError(..)
 
-  -- *** Utilities to specify Post Policy conditions
+  -- *** Post Policy condition helpers
   , PostPolicyCondition
   , ppCondBucket
   , ppCondContentLengthRange
@@ -202,9 +202,8 @@ module Network.Minio
   , ppCondSuccessActionStatus
 
   -- * Error handling
-  -----------------------
-  -- | Data types representing various errors that may occur while working
-  -- with an object storage service.
+  -- | Data types representing various errors that may occur while
+  -- working with an object storage service.
   , MinioErr(..)
   , MErrV(..)
   , ServiceErr(..)

src/Network/Minio/Data.hs

@@ -127,7 +127,8 @@ data Credentials = Credentials { cAccessKey :: Text
                                , cSecretKey :: Text
                                } deriving (Eq, Show)
 
--- | A Provider is an action that may return Credentials
+-- | A Provider is an action that may return Credentials. Providers
+-- may be chained together using 'findFirst'.
 type Provider = IO (Maybe Credentials)
 
 -- | Combines the given list of providers, by calling each one in
@@ -213,16 +214,18 @@ getHostAddr ci = if | port == 80 || port == 443 -> toS host
     host = connectHost ci
 
 
--- | Default GCS ConnectInfo. Works only for "Simple Migration"
--- use-case with interoperability mode enabled on GCP console. For
--- more information - https://cloud.google.com/storage/docs/migrating
+-- | Default Google Compute Storage ConnectInfo. Works only for
+-- "Simple Migration" use-case with interoperability mode enabled on
+-- GCP console. For more information -
+-- https://cloud.google.com/storage/docs/migrating
+--
 -- Credentials should be supplied before use.
 gcsCI :: ConnectInfo
 gcsCI = setRegion "us"
         "https://storage.googleapis.com"
 
 
--- | Default AWS ConnectInfo. Connects to "us-east-1". Credentials
+-- | Default AWS S3 ConnectInfo. Connects to "us-east-1". Credentials
 -- should be supplied before use.
 awsCI :: ConnectInfo
 awsCI = "https://s3.amazonaws.com"
@@ -244,9 +247,7 @@ type Bucket = Text
 -- Represents an object name
 type Object = Text
 
--- |
--- Represents a region
--- TODO: This could be a Sum Type with all defined regions for AWS.
+-- | Represents a region
 type Region = Text
 
 -- | A type alias to represent an Entity-Tag returned by S3-compatible APIs.

src/Network/Minio/SelectAPI.hs

@@ -29,7 +29,6 @@ module Network.Minio.SelectAPI
   , selectRequest
 
   -- *** Input Serialization
-  -------------------------
 
   , InputSerialization
   , defaultCsvInput
@@ -42,7 +41,7 @@ module Network.Minio.SelectAPI
   , setInputCompressionType
 
   -- *** CSV Format details
-  ------------------------
+
   -- | CSV format options such as delimiters and quote characters are
   -- specified using using the functions below. Options are combined
   -- monoidally.
@@ -60,7 +59,6 @@ module Network.Minio.SelectAPI
   , quoteFields
 
   -- *** Output Serialization
-  -------------------------
 
   , OutputSerialization
   , defaultCsvOutput
@@ -69,12 +67,11 @@ module Network.Minio.SelectAPI
   , outputJSONFromRecordDelimiter
 
   -- *** Progress messages
-  ------------------------
 
   , setRequestProgressEnabled
 
   -- *** Interpreting Select output
-  --------------------------------------------
+
   -- | The conduit returned by `selectObjectContent` returns values of
   -- the `EventMessage` data type. This returns the query output
   -- messages formatted according to the chosen output serialization,