[DOC] Add a note to clarify binary flags to `IO.new`

Try to make it more clear that the `File::BINARY` integer flag, and the
`b` string suffix are not equivalent.

1 files changed, 7 insertions, 1 deletions

diff --git a/io.c b/io.c
index 0a78e0b200..defdecd7d9 100644
--- a/io.c
+++ b/io.c
@@ -14212,7 +14212,7 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *  ==== Read/Write Mode Specified as an \Integer
  *
  *  When +mode+ is an integer it must be one or more (combined by bitwise OR (<tt>|</tt>)
- *  of the modes defined in File::Constants:
+ *  of the following modes:
  *
  *  - +File::RDONLY+: Open for reading only.
  *  - +File::WRONLY+: Open for writing only.
@@ -14277,6 +14277,12 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *
  *    File.open('t.tmp', 'wx')
  *
+ *  Note that when using integer flags to set the read/write mode, it's not
+ *  possible to also set the binary data mode by adding the File::BINARY flag
+ *  to the bitwise OR combination of integer flags. This is because, as
+ *  documented in File::Constants, the File::BINARY flag only disables line code
+ *  conversion, but does not change the external encoding at all.
+ *
  *  == Encodings
  *
  *  Any of the string modes above may specify encodings --