IO::Buffer improvements and documentation. (#9329)

* Restore experimental warnings.

* Documentation and code structure improvements.

* Improved validation of flags, clarified documentation of argument handling.

* Remove inconsistent use of `Example:` and add example to `null?`.

* Expose `IO::Buffer#private?` and add test.

1 files changed, 21 insertions, 0 deletions

diff --git a/test/ruby/test_io_buffer.rb b/test/ruby/test_io_buffer.rb
index dea8388d7d..f7a6557a24 100644
--- a/test/ruby/test_io_buffer.rb
+++ b/test/ruby/test_io_buffer.rb
@@ -517,4 +517,25 @@ class TestIOBuffer < Test::Unit::TestCase
   rescue NotImplementedError
     omit "Fork/shared memory is not supported."
   end
+
+  def test_private
+    omit if RUBY_PLATFORM =~ /mswin|mingw/
+
+    Tempfile.create("buffer.txt") do |io|
+      io.write("Hello World")
+
+      buffer = IO::Buffer.map(io, nil, 0, IO::Buffer::PRIVATE)
+      assert buffer.private?
+      refute buffer.readonly?
+
+      buffer.set_string("J")
+
+      # It was not changed because the mapping was private:
+      io.seek(0)
+      assert_equal "Hello World", io.read
+    ensure
+      buffer&.free
+      io&.close
+    end
+  end
 end