Document existence of buffer for in_channels, and related scenarios

[tomjridge]

In particular, that the buffer isn't updated automatically when the
underlying file data changes.

[dra27]

Thanks for this - it's definitely good to correct, especially given that the Unix module already has a warning about in_channel being buffered. A few things (bizarrely, for one paragraph!):

• The information needs to go in the new In_channel module as well. I don't think it should be specifically on open_in_gen - it could be an isolated paragraph immediately below the heading in Stdlib and as part of the opening text in In_channel (you'll have to check what the HTML output looks like - I can't remember what ocamldoc does with paragraphs in the middle of modules)
• It's nice to mention the alternative for the user who needs unbuffered input:
  • Would having an In_channel version of Add Out_channel.{is,set}_buffered to control buffering of output channels #10538 have been useful in your case? (future work, if it all, obviously)
  • In the meantime, the documentation could mention Unix.openfile + Unix.read as the "unbuffered" way of reading from a file.

[dra27]

Suggested change

	cases of this function.
	cases of this function.

For there to be a newline, ocamldoc needs a blank line following (assuming that was what you intended)?

[xavierleroy]

The information needs to go in the new In_channel module as well. I don't think it should be specifically on open_in_gen - it could be an isolated paragraph immediately below the heading in Stdlib and as part of the opening text in In_channel

Detailed information should go in In_channel with at most a brief mention in Stdlib. Let's not duplicate things.

[xavierleroy]

This said, buffered I/O behaves pretty much the same in any language (e.g. stdio.h streams in C, BufferedInputStream in Java, and in_channel in OCaml), so I'm not quite sure what needs to be documented specifically in OCaml.

[tomjridge]

I removed my comment from stdlib and added another to in_channel.mli. I also noticed that the Unix module has a lot of these "Beware that input channels are buffered" warnings, but they don't do any harm I suppose.

I can rebase/squash the changes against current trunk to tidy things if that would help.

Regarding having an unbuffered input channel #10538, I think my use case is probably better handled by normal Unix.openfile etc.

[tomjridge]

Not worth keeping open, so closing. I think I was pondering whether buffered I/O could be more "intelligent" i.e. noticing concurrent updates to a file by another process and then refreshing the buffer (or something along those lines). But this isn't the standard behaviour as Xavier says. Sorry for the noise. And thanks to David for the feedback.