ocaml/ocaml — pull request #90 by gasche (2014-08-10 12:13:02+00:00)
Title: [RFC] document the unsafe conversions Bytes.unsafe_{to,of}_string

The attached patch contains a tentative documentation of the two new functions [Bytes.unsafe_of_string] and [Bytes.unsafe_to_string] that are intended for use when migrating code to support the new `-safe-string` option.

It is only a preliminary patch; in particular, it does not contain much OCamldoc formatting (I will add those laters). I would be interested in feedback on the content. The objectives of documenting these functions are the following:

1. we do not want beginners to use them (there is no need to, given the existing `Bytes.of_string` and `Bytes.to_string` which are correct and fast enough for most purposes)
2. we do not want experts to use them wrongly or, worse, wrongly use [Obj.magic] or `"%identity" instead.

Not documenting at all is a very good way to reach goal (1), but does pretty badly on (2). Do you feel the proposed documentation is effective? How should it be improved?

Finally, be aware that documenting unsafe functions is still a controversial topic among OCaml maintainers. I'd like to get as good a proposal as possible, but it is possible that maintainers decide to keep those undocumented in any case. Invest your time wisely.