Improve documentation of Data.List.lines:

- Document behavior on some inputs.
- Add some examples.

Reviewers: bgamari, osa1, hvr, dolio, #core_libraries_committee,
nomeata, austin

Reviewed By: bgamari, dolio, #core_libraries_committee, nomeata, austin

Subscribers: dolio, glguy, nomeata, thomie

Differential Revision: https://phabricator.haskell.org/D1450

1 files changed, 14 insertions, 0 deletions

diff --git a/libraries/base/Data/OldList.hs b/libraries/base/Data/OldList.hs
index a377b4f518..be894c0877 100644
--- a/libraries/base/Data/OldList.hs
+++ b/libraries/base/Data/OldList.hs
@@ -1044,6 +1044,20 @@ unfoldr f b0 = build (\c n ->
 
 -- | 'lines' breaks a string up into a list of strings at newline
 -- characters.  The resulting strings do not contain newlines.
+--
+-- Note that after splitting the string at newline characters, the
+-- last part of the string is considered a line even if it doesn't end
+-- with a newline. For example,
+--
+-- > lines "" == []
+-- > lines "\n" == [""]
+-- > lines "one" == ["one"]
+-- > lines "one\n" == ["one"]
+-- > lines "one\n\n" == ["one",""]
+-- > lines "one\ntwo" == ["one","two"]
+-- > lines "one\ntwo\n" == ["one","two"]
+--
+-- Thus @'lines' s@ contains at least as many elements as newlines in @s@.
 lines                   :: String -> [String]
 lines ""                =  []
 -- Somehow GHC doesn't detect the selector thunks in the below code,