Some OCaml documentation comments include examples, but I’m not sure this should be encouraged, and in any event, a short documentation string can’t include all relevant examples.
Clojure’s ClojureDocs might provide a nice model for provision of small illustrative examples. ClojureDocs includes a page for each common function. The page begins with the docstring for the function [analogous to (** … *) documentation comments in OCaml], followed by community-supplied examples and comments, and then community-supplied links to related ClojureDocs pages. ClojureDocs is usually my first stop for information about a Clojure function if the docstring doesn’t tell me enough, or I’ll go there simply because it’s a nice web source for docstrings. (By way of example, here’s the page for the map function.)
It’s worth remarking that many Clojure docstrings are very compressed. Some of the docstrings are very good for learning, but the core developer team seems to think of some docstrings more as reminders than as initial learning tools. But that’s OK, in most cases, given ClojureDocs and some of the other resources available. For OCaml, too, an alternative is to keep documentation comments concise but provide examples and further comments elsewhere.
Of course, more OCaml library functions should have documentation comments in the first place!
By the way, might there be some way in the furture to give access to documentation comments in a toplevel? One of the nice things about using the Clojure repl is that (doc <function-name>) will display the docstring for any function that’s in the current namespace scope. I know that comments are long gone when one is in utop, but might there be a way of creating a documentation database, both for newly-loaded ml files and libraries, and give access to it with special toplevel commands? This is more difficult than in Clojure, I guess, since you can’t store the the documentation with the function, but it would be very useful
(I’ve wondered whether the fact that OCaml provides type signatures so readily has made it easier to put off writing documentation comments, since one important part of the documentation is provided automatically. Expected types in Clojure would be mysterious without explanatory text; maybe that’s why it’s rare that doc strings are left out (except in the source code for Clojure itself!).)