[#146] Improve documentation

Resolves #146

.travis.yml

@@ -19,10 +19,10 @@ matrix:
   - ghc: 8.0.2
   - ghc: 8.2.2
   - ghc: 8.4.4
-  - ghc: 8.6.3
+  - ghc: 8.6.4
 
   # stack
-  - ghc: 8.6.3
+  - ghc: 8.6.4
     env: STACK_YAML="$TRAVIS_BUILD_DIR/stack.yaml"
 
 install:

CHANGELOG.md

@@ -21,8 +21,11 @@ The changelog is available [on GitHub][2].
   Improve text of custom compile-time error messages for `elem` functions.
 * [#136](https://github.com/kowainik/relude/issues/136):
   Cover `Relude.Extra.*` modules with custom HLint rules.
+* [#146](https://github.com/kowainik/relude/issues/146):
+  Improve documentation for `Relude.File` file: be more explicit about system
+  locale issues.
 * Improve documentation for `One` typeclass and add tests.
-* Support ghc-8.6.3 and ghc-8.4.4.
+* Support ghc-8.6.4 and ghc-8.4.4.
   Drop support for ghc-8.6.1 and ghc-8.4.3.
 
 ## 0.4.0 — Nov 6, 2018

README.md

@@ -171,8 +171,11 @@ import Relude
     space-efficient). So you should write `sortOn length` (would sort elements
     by length) but `sortWith fst` (would sort list of pairs by first element).
 * Functions `sum` and `product` are strict now, which makes them more efficient.
-* Since `show` doesn't come from `Show` anymore, you need to export `Show` from
-  `Text.Show` module if you want to implement `Show` instance manually.
+* Since `show` doesn't come from `Show` anymore, you need to export
+  `Text.Show` module if you want to implement `Show` instance manually. This can be done like this:
+  ```haskell
+  import qualified Text.Show
+  ```
 * You can't call `elem` and `notElem` functions over `Set` and `HashSet`. These
   functions are forbidden for these two types because of the performance reasons.
 * `error` takes `Text`.
@@ -239,7 +242,7 @@ Also, `toText/toLText/toString` can convert `Text|LText|String` types to
 `Text/LText/String`. If you want to convert to and from `ByteString` use
 `encodeUtf8/decodeUtf8` functions.
 
-### transforms & mtl
+### transformers & mtl
 
 The following parts of these two libraries are exported:
 
@@ -312,7 +315,7 @@ Finally, we can move to part describing the new cool features we bring with `rel
 ### Need to import explicitly
 
 * Convenient functions to work with `(Bounded a, Enum a)` types:
-  1. `universe :: (Bounded a, Enum a) => [a`: get all values of the type.
+  1. `universe :: (Bounded a, Enum a) => [a]`: get all values of the type.
   2. `inverseMap :: (Bounded a, Enum a, Ord k) => (a -> k) -> k -> Maybe a`: convert functions like `show` to parsers.
 * Nice helpers to deal with `newtype`s in a more pleasant way:
 
@@ -376,7 +379,6 @@ This section describes what you need to change to make your code compile with `r
 
 5. Forget about `String` type.
    + Replace `(++)` with `(<>)` for `String`-like types.
-   + Try to use [`fmt`](http://hackage.haskell.org/package/fmt) library if you need to construct messages.
    + Use `toText/toLText/toString` functions to convert to `Text/LazyText/String` types.
    + Use `encodeUtf8/decodeUtf8` to convert to/from `ByteString`.
    + Use `(putStr[Ln]|readFile|writeFile|appendFile)[Text|LText|BS|LBS]` functions.

relude.cabal

@@ -57,7 +57,7 @@ build-type:          Simple
 tested-with:         GHC == 8.0.2
                    , GHC == 8.2.2
                    , GHC == 8.4.4
-                   , GHC == 8.6.3
+                   , GHC == 8.6.4
 extra-doc-files:     CHANGELOG.md
                    , CONTRIBUTING.md
                    , README.md

src/Relude/File.hs

@@ -3,8 +3,14 @@ Copyright:  (c) 2018-2019 Kowainik
 License:    MIT
 Maintainer: Kowainik <xrom.xkov@gmail.com>
 
-Functions to work with files for 'Text', 'LText', 'ByteString' and 'LByteString'
-types.
+Lifted to 'MonadIO' families of file processing functions for 'Text', 'LText',
+'ByteString' and 'LByteString' types.
+
+__NOTE:__ Functions that work with 'Text' or 'LText' types are sensitive to
+system locale. If not sure, use functions that work with 'ByteString'. See the
+following blog post for more details:
+
+* https://www.snoyman.com/blog/2016/12/beware-of-readfile
 -}
 
 module Relude.File
@@ -47,7 +53,7 @@ import qualified Data.Text.Lazy.IO as LT
 readFileText :: MonadIO m => FilePath -> m Text
 readFileText = liftIO . T.readFile
 {-# SPECIALIZE readFileText :: FilePath -> IO Text #-}
-{-# INLINE readFileText #-}
+{-# INLINE     readFileText #-}
 
 -- | Lifted version of 'T.writeFile'.
 writeFileText :: MonadIO m => FilePath -> Text -> m ()
@@ -69,7 +75,7 @@ appendFileText p = liftIO . T.appendFile p
 readFileLText :: MonadIO m => FilePath -> m LText
 readFileLText = liftIO . LT.readFile
 {-# SPECIALIZE readFileLText :: FilePath -> IO LText #-}
-{-# INLINE readFileLText #-}
+{-# INLINE     readFileLText #-}
 
 -- | Lifted version of 'LT.writeFile'.
 writeFileLText :: MonadIO m => FilePath -> LText -> m ()
@@ -91,7 +97,7 @@ appendFileLText p = liftIO . LT.appendFile p
 readFileBS :: MonadIO m => FilePath -> m ByteString
 readFileBS = liftIO . BS.readFile
 {-# SPECIALIZE readFileBS :: FilePath -> IO ByteString #-}
-{-# INLINE readFileBS #-}
+{-# INLINE     readFileBS #-}
 
 -- | Lifted version of 'BS.writeFile'.
 writeFileBS :: MonadIO m => FilePath -> ByteString -> m ()
@@ -113,7 +119,7 @@ appendFileBS p = liftIO . BS.appendFile p
 readFileLBS :: MonadIO m => FilePath -> m LByteString
 readFileLBS = liftIO . LBS.readFile
 {-# SPECIALIZE readFileLBS :: FilePath -> IO LByteString #-}
-{-# INLINE readFileLBS #-}
+{-# INLINE     readFileLBS #-}
 
 -- | Lifted version of 'LBS.writeFile'.
 writeFileLBS :: MonadIO m => FilePath -> LByteString -> m ()

src/Relude/Foldable/Fold.hs

@@ -61,6 +61,8 @@ import qualified Data.Foldable as F
 
 >>> flipfoldl' (/) 5 [2,3] :: Rational
 15 % 2
+
+This functions can be useful for constructing containers from lists.
 -}
 flipfoldl' :: Foldable f => (a -> b -> b) -> b -> f a -> b
 flipfoldl' f = foldl' (flip f)

stack.yaml

@@ -1,4 +1,4 @@
-resolver: lts-13.6
+resolver: lts-13.13
 
 extra-deps:
   - tasty-hedgehog-0.2.0.0