Obj module documentation
Is there any documentation about the Obj module? I could only find a list of functions without any description...
(BTW: I know these are low-level functions not meant to be generally used)
Yes, it is clearly undocumented on purpose. For five uses of Obj I see (or write myself, which is more disturbing), two of them are unjustified, two of them are a way to avoid a cleaner design change that would be useful anyway, and one of them is a genuine "good solution" to a complicated problem.
Obj only expose type-breaking operations that allow to explore and manipulate the runtime representation of OCaml data. You don't need documentation for these functions, they're obvious, but you need to know about OCaml data representation (I learned it using this document, but the ocaml manual also documents it), and if you want to hack into it you should know about the runtime to know what's safe and what isn't. As a general rule: don't.
Here are a few legitimate uses of Obj:
when compiling Coq programs to OCaml programs; the Coq type system being more powerful, it can type things that OCaml would reject, hence the Coq->Ocaml translator inserts Obj.magic calls to force OCaml into accepting its output.
when encoding GADTs in OCaml 3.x, which didn't support it -- they were added to 4.00. There is one encoding with module-level equality and functors (see this post or this work), but the more common one (used in the menhir parser generator which is a great replacement for ocamlyacc, see this paper (PDF)) uses Obj.magic
when marshalling data using some kind of (home-made) runtime type information. The Marshal module of OCaml is already not type-safe (for obvious reason), and if you need a different kind of marshalling in a different context (eg. to/from queries and results for a SQL server, as I did in my macaque project) you will need some kind of unsafe cast.
The module Obj basically deals with the structure and interpretation of OCaml values in the heap. If you want to understand what this means you must read chapter 18 of the OCaml manual, "Interfacing C with Objective Caml".
The reason why this is undocumented is twofold: first of all, the functions are horribly unsafe. There is simply no total function with type 'a -> 'b so you can see that Obj.magic must do quite a bit of it if it is to return anything at all. In fact it is just a hole into the type system, a "license to kill" it. Second, the module allows you to peek and poke into the heap at will, in effect providing the moral equivalent of C's pointers to void. This together with unrestricted casts lets you do whatever you want from OCaml.
There are legitimate uses for Obj, though. I count more than 100 occurrences of Obj.magic in the sources, most notably in the code for Printf and Scanf. Another legitimate use is for tail-recursive list operations, provided you can prove that the code is type-safe and thread-safe.
If you don't mind the self-plugs, here is an example of an unsafe operation that is wrapped in a safe interface, together with a proof ("Since at each step the cons cell is fresh…") that it is indeed safe, and here is another.