Document exceptions

[copy]

The exceptions that are raised should be documented, in particular what happens when an invalid image file is loaded and when Image.read_rgb is used with invalid bounds. result-returning variants would also be nice.

Also, the library should build and install mli, cmt, cmti and cmx files, so that documentation can be viewed by tools like merlin, ocp-browser, odig, etc.

[cfcs]

I agree re: documenting exceptions, it would be nice if someone took the time to go through and document these.

result:
@rlepigre previously expressed that they are not so fond of result (in this comment), but I personally prefer result. I think that wrapper functions that returned result types would be an OK compromise, but let's hear @rlepigre out.

Re: Installation: ocp-browser has no problems. As you can see .cmi (and .mli) files are included below.
cmx files contain the code itself; without cmx you can't link it when compiling native applications.

.cmt and .cmti are built when you pass -bin_annot to the compiler (look for safe_string in GNUmakefile for an example of how to do this). I do not know what the binary annotations are used for, but it is simple to enable their building. :)

List of files installed by the opam package:

~/.opam/4.04.2+fPIC/lib/imagelib$ ls
image.cmi     imageJPG.cmo  imagelib.cmxa  imagePNG.o     imageUtil.o
image.cmo     imageJPG.cmx  imageLib.mli   imagePPM.cmi   imageXCF.cmi
image.cmx     imageJPG.o    imageLib.o     imagePPM.cmo   imageXCF.cmo
imageGIF.cmi  imagelib.a    image.mli      imagePPM.cmx   imageXCF.cmx
imageGIF.cmo  imagelib.cma  image.o        imagePPM.o     imageXCF.o
imageGIF.cmx  imageLib.cmi  imagePNG.cmi   imageUtil.cmi  META
imageGIF.o    imageLib.cmo  imagePNG.cmo   imageUtil.cmo  opam.config
imageJPG.cmi  imageLib.cmx  imagePNG.cmx   imageUtil.cmx

[copy]

I do not know what the binary annotations are used for, but it is simple to enable their building.

These are used by merlin for locate, document, and probably a few others. I believe ocp-browser uses them to show documentation.

[rlepigre]

To come back on the result type VS exception debate, my reasons are simple: OCaml is not Haskell, and that's for the best. Monads and that kind of stuff may look cool, but they lead to a code that can be really hard to apprehend (for most people). Moreover, there is absolutely nothing wrong about using exceptions in exceptional situations! Especially in high-level libraries like imagelib. And as mentioned above, it is always possible to write wrapper functions if you prefer result type, but I'm not sure that we should include these in the library.

For the documentation issue, I'll do my best to update the documentation, but I'm going to be very busy in the next few weeks.