Expand memSlices doc comment & use better example.

Have lines() iterators docs point back to memSlices() for details.

lib/pure/memfiles.nim

@@ -12,8 +12,8 @@
 ## This module provides support for `memory mapped files`:idx:
 ## (Posix's `mmap`:idx:) on the different operating systems.
 ##
-## It also provides some fast iterators over lines in text files
+## It also provides some fast iterators over lines in text files (or
-## delimited in Unix or Windows styles (or similarly delimited records).
+## other "line-like", variable length, delimited records).
 
 when defined(windows):
   import winlean
@@ -262,17 +262,29 @@ proc `$`*(ms: MemSlice): string {.inline.} =
   result = buf
 
 iterator memSlices*(mfile: MemFile, delim='\l', eat='\r'): MemSlice {.inline.} =
-  ## Iterates over [optional eat]delim-delimited slices in a MemFile.
+  ## Iterates over [optional `eat`] `delim`-delimited slices in MemFile `mfile`.
-  ## Default delimiting is [\\r]\\l which parses Unix/Windows text file lines.
+  ##
-  ## Pass eat='\\0' to be strictly delim-delimited.
+  ## Default parameters parse lines ending in either Unix(\\l) or Windows(\\r\\l)
-  ## This zero copy, memchr-limited method is probably the fastest way to
+  ## style on on a line-by-line basis.  I.e., not every line needs the same ending.
-  ## iterate through lines in a file.  The returned (data,size) objects are
+  ## Unlike readLine(File) & lines(File), archaic MacOS9 \\r-delimited lines
-  ## NOT Nim strings or even terminated C strings.  So, be careful how data
+  ## are not supported as a third option for each line.  Such archaic MacOS9
-  ## is accessed (e.g., think C mem* functions, not str* functions).  Example:
+  ## files can be handled by passing delim='\\r', eat='\\0', though.
+  ##
+  ## Non-default delimiters can be passed to allow iteration over other sorts
+  ## of "line-like" variable length records.  Pass eat='\\0' to be strictly
+  ## `delim`-delimited. (Eating an optional prefix equal to '\\0' is not
+  ## supported.)
+  ##
+  ## This zero copy, memchr-limited interface is probably the fastest way to
+  ## iterate over line-like records in a file.  However, returned (data,size)
+  ## objects are not Nim strings, bounds checked Nim arrays, or even terminated
+  ## C strings.  So, care is required to access the data (e.g., think C mem*
+  ## functions, not str* functions).  Example:
   ##
   ## .. code-block:: nim
   ##   var count = 0
   ##   for slice in memSlices(memfiles.open("foo")):
+  ##     if slice.size > 0 and cast[cstring](slice.data)[0] != '#':
   ##       inc(count)
   ##   echo count
 
@@ -298,13 +310,14 @@ iterator memSlices*(mfile: MemFile, delim='\l', eat='\r'): MemSlice {.inline.} =
 
 iterator lines*(mfile: MemFile, buf: var TaintedString, delim='\l', eat='\r'): TaintedString {.inline.} =
   ## Replace contents of passed buffer with each new line, like readLine(File).
-  ## Default delimiting is [\\r]\\l which parses Unix/Windows text file lines.
+  ## `delim`, `eat`, and delimiting logic is exactly as for memSlices, but Nim
-  ## Pass eat='\\0' to be strictly delim-delimited.  Example:
+  ## strings are returned.  Example:
   ##
   ## .. code-block:: nim
   ##   var buffer: TaintedString = ""
   ##   for line in lines(memfiles.open("foo"), buffer):
   ##     echo line
+
   for ms in memSlices(mfile, delim, eat):
     buf.setLen(ms.size)
     c_memcpy(addr(buf[0]), ms.data, ms.size)
@@ -313,8 +326,8 @@ iterator lines*(mfile: MemFile, buf: var TaintedString, delim='\l', eat='\r'): T
 
 iterator lines*(mfile: MemFile, delim='\l', eat='\r'): TaintedString {.inline.} =
   ## Return each line in a file as a Nim string, like lines(File).
-  ## Default delimiting is [\\r]\\l which parses Unix/Windows text file lines.
+  ## `delim`, `eat`, and delimiting logic is exactly as for memSlices, but Nim
-  ## Pass eat='\0' to be strictly delim-delimited.  Example:
+  ## strings are returned.  Example:
   ##
   ## .. code-block:: nim
   ##   for line in lines(memfiles.open("foo")):