Hacker News new | ask | show | jobs
by bordoley 3369 days ago
Hi Drup,

The intent of Immutable-re is to provide a complete set of persistent immutable collections that complement the standard library and core. The initial release is limited to common Map, Set, and Vector types, but we have intent to add additional collections such as BiMaps, Multisets, and Multimaps. There is of course some overlap with the stdlib collections (SortedSet vs. OCaml Set, SortedMap vs. OCaml Map) but even in these cases, the Immutable-re implementations have slightly different characteristics from their stdlib counterparts, which provide added value.

The public API is designed to be very Reason like, and familiar to web developers with experience in JavaScript, Java and C#, hence the naming conventions and camlCase. I've also considered adding an OCaml compatibility layer, which provides a more familiar API for OCaml developers. While the public API itself is heavily dependent upon signature indirection, these signatures are purely for documentation and not heavily depended upon within the implementation, which means the OCaml compat API may not include them at all.

Regarding the choice of APIs for sequences, the current Sequence type is intentionally opaque and is internally designed to be compatible with the proposed standard OCaml Sequence (https://github.com/ocaml/ocaml/pull/1002). If/when, that PR lands, we will switch our internal implementation to be compatible with OCaml's while maintaining the same public API.

Finally you are completely correct regarding documentation generation. Unfortunately refmt does not currently support outputting OCaml mli files including comments. This left me with the choice of hand rolling docs as I did or shipping ocamldocs lacking any comments explaining the types and functions. I chose the former.

Thanks for your feedback.
1 comments
Drup 3369 days ago
Well, multisets, multimaps and a lot of other things are also provided in containers and core. It's nice that you (already!) adopted that style of iterator.

I'm not sure what an "OCaml compatibility layer" would mean. It's already OCaml-y: it's referentially transparent and full of functors and signatures! The main weird thing is that the type of compare is not the same (I understand why, but I find compatibility more valuable). The naming convention matters little, as long as it's clear, readable and consistent (OCamlers are not going to boycott a library because it uses camlCase).

I don't think the signature indirection is a real problem, you just need a good tool for documentation generation that inlines signatures. You can ask the odoc people, I'm sure they would be happy to help you. I'm surprised there is no "reasondoc" tool just yet. :)

link