Document caml_result in the manual (FFI chapter)

[gasche]

This PR is a companion to #13013, providing documentation for the new caml_result type and convention in the OCaml manual, FFI chapter.

I mostly removed the documentation of the previous encoded-exceptions API, except for in-passing mentions that it may still be used for compatibility with pre-5.3 codebases. People who need to understand the encoded-exception API will have to look for older versions of the manual.

[gasche]

Thanks @dustanddreams and @dbuenzli, I took your comments into account. I also actually checked that the example compiles (not bad, I only wrote caml_alloc2 instead of caml_alloc_2) and used an itemized list for a more structure presentation of the caml_result API.

[NickBarnes]

Looks good to me (apart from that one typo).

[gadmm]

This looks good to me.

You could also add a link to the section ss:c-result in the last paragraph of the section ss:c-exceptions which mentions the caml_exception_* functions.

[ghost]

Shouldn't this get merged soon since #13013 has been?

[gasche]

I would certainly be in favor and/but this requires the approval of a maintainer.

(I also need to do another round on the feedback of @gadmm -- thanks! -- but this seems orthogonal to approval.)

[gasche]

I took the comments of @gadmm and @MisterDA into account (thanks!) and rebased the PR. This still needs a maintainer approval to be merged.

[shindere]

Just approved. I didn't merge yet because I noticed a discrepancy between the reviewers mentionned in the commit andthose mentionned in theChanges entry. I don'tmind but wated to give an opportunity forthisto be fixed, if you wanted so, @gashce. Feel free to merge whenever you like as far asI am concerned.

[gasche]

Thanks @shindere! When I restarted working on this PR I had forgotten that it had its own Changes entry, so I used commit metadata (which I don't normally use) to credit reviewers. This is fixed now -- the Changes has all names, and I removed the Reviewed-by tag, nothing against them but they are not standard practice in OCaml land so there is little point in using them just once.