On finding documentation

Question

So far, giving Google search strings such as

"ocaml" regex

"ocaml" hashtbl

etc. has usually gotten me the documentation I've been looking for.

One notable exception has been

"ocaml" "String.Map"

With this search, all I can find (documentation-wise, that is), is documentation for the String.map function of the String module (or is it "package"?). (If understand correctly, String.Map is a data structure, namely a map whose keys have type string, rather than a function.)

Even more forceful Google search specs like

"ocaml" intitle:"String.Map"

...failed to find the documentation I'm after.

Is there a less haphazard, and more general, way to zero-in the documentation for a particular standard item in OCaml?

(I added the "and more general" bit above because using a search engine is not practical when one wants to search for non-alphabetic items such as |>, >>, etc., or for items where some non-alphabetic feature is critical to one's question, such as when one wants to learn about the difference between 'a and '_a, or when the search is case-sensitive, as my current search.)

PS: I had no luck with the obvious places, such as

https://ocaml.org
http://caml.inria.fr/pub/docs/manual-ocaml/libref/
https://opam.ocaml.org/packages/

(This is not to say it's not "somewhere" accessible through some of those links; I'm just not seeing it.)

I did no better with some desperate guesses, like

http://caml.inria.fr/pub/docs/manual-ocaml/libref/String.Map.html (status code 404)

EDIT: Here's another search that fails to turn up any documentation page:

"ocaml" "of_alist_exn"

If, as I understand it, of_alist_exn is a function in some standard OCaml module, then I find it shocking that the search above fails. (I get 18 hits, and not a single one of them looks to me (based on the info available in a Google results list) like a documentation page.)

I've learned the basics of other computer languages from "passive" online resources: tutorials and official documentation. And not by reading this documentation linearly cover-to-cover, but by searching for what I wanted to know as I needed to. I'm finding it impossible to learn even the basics of OCaml this way. I wonder how other people have managed to learn it... I have to assume it is mostly by getting crucial-but-undocumented information via word-of-mouth (chatrooms, etc.)...

ivg ivg · Accepted Answer · 2014-11-09T16:53:27

You need to know some background on OCaml standard libraries. There is a standard library that ships with the the compiler, lets call it stdlib. It is nice, but very thin library, that was written many years ago. That's why people wrote several alternatives: Core, Batteries, extlib, to name a few.

There is nothing wrong with OCaml stdlib, but it is very small. But it can be considered as an advantage, especially if you're using OCaml as language for a college level computer science course. But if you're a professional software develope, then you will soon find that it is too short. That's why there is an OCaml Core library from Janestreet. It is very prominent library, with much higher entrance level than stdlib. So, I'm assuming that you're using this library (and I think that you made a right choice, but this is only my opinion).

Core library is an overlay over a standard library. It uses different naming conventions, and they try to hide definitions from the standard library. Although many still leaks. You shouldn't mix vanilla standard library with core, until you're really forced to. And in that case, you should explicitly use Caml module, that exports entire stdlib.

Now, back to the question. The official documentation for Core library can be found with a simple ocaml core documentation query, that will yield you a link to official core documentation. As you may see there're lots of modules there. You should start from Std module, this is a module that exports what they think that they should export (cf., __init__.py). Inside of this module you may find String submodule. You may even see, that it is reexported into your namespace from the Core_string module (module String : Core_string). This is the module you were searching for. You can click, the tiny + symbol too look inside the module, but, this is a point of ugliness, there will be only signatures, but no documentation. Yes, I know, it sucks, but later about this. So, in order to receive full documentation, you need to click on Core_string module, et voila. So, by trial and error we found it. The process is really not friendly, or not as friendly as it could be, but this is only because no one (sic) actually move in this way. There is a better way. There're tools, that you should master, to be really productive with OCaml, and it is emacs, merlin, ocp-index, ocamlspot. Of course, you can substitute emacs for vim, if you would like.

So, once you have installed, configured and mastered these tools, you can do your coding without ever leaving your favorite editor. First of all, you can lookup for a documentation directly from the mli files. Indeed, mli is a killing feature of OCaml language. For example, if I need to refresh my knowledge on the String.strip function, I just point my emacs to the Core_string.mli module, and read these:

(* Warning: the following strip functions have copy-on-write semantics (i.e. they may
   return the same string passed in) *)

(** [lstrip ?drop s] returns a string with consecutive chars satisfying [drop] (by default
    white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the
    beginning of [s]. *)
val lstrip : ?drop:(char -> bool) -> t -> t

(** [rstrip ?drop s] returns a string with consecutive chars satisfying [drop] (by default
    white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the end
    of [s]. *)
val rstrip : ?drop:(char -> bool) -> t -> t

(** [strip ?drop s] returns a string with consecutive chars satisfying [drop] (by default
    white space, e.g. tabs, spaces, newlines, and carriage returns) stripped from the
    beginning and end of [s]. *)
val strip : ?drop:(char -> bool) -> t -> t

It is excellent documentation, imo. Also there is warning, that you won't see in a documentation generated from this file.

P.S. There is a work in progress on making OCaml's documentation better. Sooner or later, it will become much better and accessible. But currently it is a little bit hackerish.

On finding documentation

2 Answers