improving the {In,Out}_channel documentation

[gasche]

(I made this suggestion in #10545 (comment) , but I am moving it to its own issue to make it easier to discuss. I think it could be a nice contribution from someone unfamiliar with the OCaml compiler codebase.)

I had a look at the documentation of In_channel in the manual, and I think that it would benefit from a better organization.

Current .mli definition:
https://github.com/ocaml/ocaml/blob/8e12c01/stdlib/in_channel.mli

It would be nice to have:

• sections that group the function in related clusters, with the more common first (we probably don't need functions about seeking mixed in the middle of the documentation, for example)
• a code example or two that demonstrates the basic features that everybody needs (with_open and input_all, I guess?)

(Same for Out_channel I guess?)

Related work:

• @dbuenzli has done similar work on String and Set and Map.
• @c-cube has worked on examples for various stdlib modules; note the suggested approach to have the examples at the end of the module with a forward reference at the beginning. The queue.mli documentation can be taken as an example to reproduce this pattern.

We could of course consider all the modules of the standard library, and we definitely should! But {In,Out}_channel are very recent so we have a chance to make the documentation good before most prospective users encounter it.

[Gopiandcode]

I'd like to take a stab at this!

[gasche]

This is great, thanks @Gopiandcode!

[dbuenzli]

This can be closed.

[gasche]

Now which module should we open an issue about next?