Fix 24339 - std.mmfile has poor documentation

std/mmfile.d

@@ -2,10 +2,22 @@
 
 /**
  * Read and write memory mapped files.
+ *
+ * Memory mapped files are a mechanism in operating systems that allows
+ * file access through virtual memory. After opening a file with `MmFile`,
+ * the contents can be read from or written to with standard slice / pointer operations.
+ * Changes to the memory are automatically reflected in the underlying file.
+ *
+ * Memory mapping can increase I/O performance of large files, compared to buffered
+ * read / write operations from `std.file` and `std.stdio`. However, I/O errors are
+ * not handled as safely: when for example the disk that the file is on gets removed,
+ * reading from it may result in a segfault.
+ *
  * Copyright: Copyright The D Language Foundation 2004 - 2009.
  * License:   $(HTTP www.boost.org/LICENSE_1_0.txt, Boost License 1.0).
  * Authors:   $(HTTP digitalmars.com, Walter Bright),
  *            Matthew Wilson
+ * References: $(LINK https://en.wikipedia.org/wiki/Memory-mapped_file)
  * Source:    $(PHOBOSSRC std/mmfile.d)
  *
  * $(SCRIPT inhibitQuickIndex = 1;)
@@ -612,23 +624,45 @@ private:
     {
         static assert(0);
     }
+}
 
-    // Report error, where errno gives the error number
+/// Read an existing file
-    // void errNo()
+@system unittest
-    // {
+{
-    //     version (Windows)
+    import std.file;
-    //     {
+    std.file.write(deleteme, "hello"); // deleteme is a temporary filename
-    //         throw new FileException(filename, GetLastError());
+    scope(exit) remove(deleteme);
-    //     }
+
-    //     else version (linux)
+    // Use a scope class so the file will be closed at the end of this function
-    //     {
+    scope mmfile = new MmFile(deleteme);
-    //         throw new FileException(filename, errno);
+
-    //     }
+    assert(mmfile.length == "hello".length);
-    //     else
+
-    //     {
+    // Access file contents with the slice operator
-    //         static assert(0);
+    // This is typed as `void[]`, so cast to `char[]` or `ubyte[]` to use it
-    //     }
+    const data = cast(const(char)[]) mmfile[];
-    // }
+
+    // At this point, the file content hasn't been read yet.
+    // The OS will
+    assert(data[0 .. 5] == "hello");
+}
+
+/// Write a new file
+@system unittest
+{
+    import std.file;
+    scope(exit) remove(deleteme);
+
+    scope mmfile = new MmFile(deleteme, MmFile.Mode.readWriteNew, 5, null);
+    assert(mmfile.length == 5);
+
+    // Assign through operator overload of `MmFile`
+    auto data = cast(ubyte[]) mmfile[];
+    data[] = '\n';
+
+    mmfile.flush();
+
+    assert(std.file.read(deleteme) == "\n\n\n\n\n");
 }
 
 @system unittest