mark add_len / set_len as deprecated

[hannesm]

extracted from #245 to stay focused there. I haven't seen any voice for keeping add_len and set_len -- though there's still work to be done until we can remove these function (as @talex5 listed here):
Other uses of set_len and add_len (from e.g. https://github.com/search?q=org%3Amirage+add_len&type=Code):

• https://github.com/mirage/mirage-block-xen/blob/master/lib/block_request.ml#L67 ("merge adjacent cstruct buffers"; add new cstruct function for this?)
• https://github.com/mirage/ocaml-git/blob/master/src/git/helper.ml#L219 (don't know what this does - @dinosaure?) -- see Remove Cstruct.add_len and deep unsafe behavior, use ke instead ocaml-git#345 which removed it
• https://github.com/mirage/ocaml-vmnet/blob/38d156580f55404d25d5b76e3343aa418c5ccf56/lib/vmnet.ml (possibly using it as a truncate? maybe add a non-deprecated truncate function for that?)
• https://github.com/mirage/ocaml-openflow/blob/dcda113745e8edc61b5508eb8ac2d1e864e1a2df/lib/ofsocket.ml (dead? no updates since 2013)
• https://github.com/mirage/mirage-tcpip/blob/ee3e8a3335c620e311a6d36d55539294a2c64ca6/src/tcp/tcp_packet.ml (used as truncate) -- see get rid of soon-deprecated Cstruct.set_len, use Cstruct.sub instead mirage-tcpip#403

[dinosaure]

ocaml-git does not use add_len anymore which is error-prone 👍

[avsm]

I am good with the deprecation, but could we add some instructions to the deprecation string to note that:

• it'll be removed in version 5.0.0 (this helps packagers set the constraints from the logs)
• what to do if they are still using that function (look at Cstruct.xxx instead)

(I am basing this off Lwt's excellent mode of deprecating which actually embeds the version number so there's a clear path for users when they see the message)

[hannesm]

@avsm of course, if we agree on when to remove these functions.

AFAICT, there is no replacement for these two functions. as talex5 mentioned above, there may be need for a truncate function, and we have to figure out what to replace them with on a case-by-case study. they are not used widely, so IMHO it is better to deprecate them now instead of waiting until we have a replacement for them. in addition, it is still unclear to me what the semantics (esp. in error cases) of add_len and set_len should be, maybe you know more about that?

my intuition was always: when i have a Cstruct.t as view on data, there's no way to look left and right of the cstruct. and the above functions (together with sub atm) violate that. of course, my intuition may be wrong -- pls let me know if I've misunderstood this library, or assumed too much.

[hannesm]

I rebased and added some information to the [@@ocaml.deprecated] attribute.

[hannesm]

rebased again, imho good to merge