From 338a93f1197fe135e31b13865ab0ef6aa9ee9864 Mon Sep 17 00:00:00 2001
From: Grzegorz Adam Hankiewicz <gradha@imap.cc>
Date: Mon, 30 Dec 2013 12:47:01 +0100
Subject: [PATCH] Adds docstrings to lines() iterators.

---
 lib/system.nim | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/lib/system.nim b/lib/system.nim
index 56bb6fe75c..0257670f4c 100644
--- a/lib/system.nim
+++ b/lib/system.nim
@@ -2236,8 +2236,19 @@ when not defined(JS): #and not defined(NimrodVM):
 
   when hostOS != "standalone":
     iterator lines*(filename: string): TaintedString {.tags: [FReadIO].} =
-      ## Iterate over any line in the file named `filename`.
-      ## If the file does not exist `EIO` is raised.
+      ## Iterates over any line in the file named `filename`.
+      ##
+      ## If the file does not exist `EIO` is raised. The iterated lines will be
+      ## stripped off the trailing newline character(s). Example:
+      ##
+      ## .. code-block:: nimrod
+      ##   import strutils
+      ##
+      ##   proc transformLetters(filename: string) =
+      ##     var buffer = ""
+      ##     for line in filename.lines:
+      ##       buffer.add(line.replace("a", "0") & '\x0A')
+      ##     writeFile(filename, buffer)
       var f = open(filename)
       var res = TaintedString(newStringOfCap(80))
       while f.readLine(res): yield res
@@ -2245,6 +2256,17 @@ when not defined(JS): #and not defined(NimrodVM):
 
     iterator lines*(f: TFile): TaintedString {.tags: [FReadIO].} =
       ## Iterate over any line in the file `f`.
+      ##
+      ## The iterated lines will be stripped off the trailing newline
+      ## character(s). Example:
+      ##
+      ## .. code-block:: nimrod
+      ##   proc countZeros(filename: TFile): tuple[lines, zeros: int] =
+      ##     for line in filename.lines:
+      ##       for letter in line:
+      ##         if letter == '0':
+      ##           result.zeros += 1
+      ##       result.lines += 1
       var res = TaintedString(newStringOfCap(80))
       while f.readLine(res): yield res