More raise less fail

[raphael-proust]

raise and reraise are "better" than fail for backtracing and such

[MisterDA]

Is that documented in the manual/docs? Should code using Lwt switch to raise/reraise?

[raphael-proust]

Is that documented in the manual/docs? Should code using Lwt switch to raise/reraise?

reraise is documented in the doc https://github.com/ocsigen/lwt/blob/master/src/core/lwt.mli#L581 / https://ocaml.org/p/lwt/latest/doc/Lwt/index.html#val-reraise

and it is recommended to use in the documentation of catch and try_bind.

The use of raise (instead of fail) is recommended in the documentation of fail and has been for quite some time now: https://github.com/ocsigen/lwt/blob/master/src/core/lwt.mli#L453 / https://ocaml.org/p/lwt/latest/doc/Lwt/index.html#val-fail

Use Lwt.fail only when you specifically want to create a rejected promise, to pass to another function, or store in a data structure.

---

Note that it's better for users to use raise+reraise, but ultimately, even if they use fail this PR does not affect them negatively.