Clarify newFileSize & mappedSize params in memfiles.open() docs

1 files changed, 16 insertions, 3 deletions

diff --git a/lib/pure/memfiles.nim b/lib/pure/memfiles.nim
index 807f3da43..97220b90b 100644
--- a/lib/pure/memfiles.nim
+++ b/lib/pure/memfiles.nim
@@ -74,9 +74,22 @@ proc unmapMem*(f: var TMemFile, p: pointer, size: int) =
 proc open*(filename: string, mode: TFileMode = fmRead,
            mappedSize = -1, offset = 0, newFileSize = -1): TMemFile =
   ## opens a memory mapped file. If this fails, ``EOS`` is raised.
-  ## `newFileSize` can only be set if the file is not opened with ``fmRead``
-  ## access. `mappedSize` and `offset` can be used to map only a slice of
-  ## the file.
+  ## `newFileSize` can only be set if the file does not exist and is opened
+  ## with write access (e.g., with fmReadWrite). `mappedSize` and `offset`
+  ## can be used to map only a slice of the file. Example:
+  ##
+  ## .. code-block:: nimrod
+  ##   var
+  ##     mm, mm_full, mm_half: TMemFile
+  ##
+  ##   mm = memfiles.open("/tmp/test.mmap", mode = fmWrite, newFileSize = 1024)    # Create a new file
+  ##   mm.close()
+  ##
+  ##   # Read the whole file, would fail if newFileSize was set
+  ##   mm_full = memfiles.open("/tmp/test.mmap", mode = fmReadWrite, mappedSize = -1)
+  ##
+  ##   # Read the first 512 bytes
+  ##   mm_half = memfiles.open("/tmp/test.mmap", mode = fmReadWrite, mappedSize = 512)
 
   # The file can be resized only when write mode is used:
   assert newFileSize == -1 or mode != fmRead