OCaml Documentation Open Thread

Ecosystem
147

I was reading Using Core_kernel.List.mem. And why usingBase&Core instead of stdlib? and there was some discussion by @perry and @Yaron_Minsky about Jane Street docs (and Base/Core in particular). In particular, @perry had some thoughts: Using Core_kernel.List.mem. And why usingBase&Core instead of stdlib?

I wanted to drop a reference here and follow-up with some thoughts of my own.

To summarize:

  1. There is too much indirection from the entry-point of documentation to the modules of interest.
  2. For some important function (e.g. Hashtbl.create) the parameters are not documented.

I agree with (1), but also admit that this is likely an issue that can be solved by tooling (as @Yaron_Minsky mentioned). I tend actually not to agree that (2) is a major issue. That being said, a very closely related issue to (2) is understanding the use of first-class modules in Base/Core.

I find that people who are getting started with JS libraries have a difficult time getting a hold of the types they want (e.g. a Map) but once they know how to create one, they have no issue looking through the docs and figuring out what the different operations do (find, find_exn, etc.)

Some of how to use the first-class modules is explained in Real World OCaml (and this is often where I point people who ask me), but perhaps a more complete description would be useful.

Admittedly, some of this will become more approachable as the “indirection problem” is solved. The type (module Base__.Hashtbl_intf.Key with type t = 'a) would look a lot less scary if it looked like (module Base.Hashtbl.Key with type t = 'a).

The other question I get is: “Okay, I get that I have to pass a module as the argument here, and that the module has to satisfy the interface … but how do I get one of those modules?”

So, often people don’t realize that many of the standard types that you might want to use as the key type in a Map/Hashtbl are designed to satisfy that interface. For example, if I’m new and don’t know any better I may just go to https://ocaml.janestreet.com/ocaml-core/latest/doc/base/Base/String/ and then get discouraged because there’s no indication that this module satisfies the interface for Hashtbl keys.

Hope this is helpful, just trying to transfer the conversation back to this thread and add my 2 cents.

1 Like