OCaml Documentation Open Thread


#21

Absolutely, see this odoc issue and the comment linked from there.


#22

On documentation searching: in the spirit of odig’s local documentation, you can also use ocp-browser which is a small CLI tool to search your locally installed modules.


#23

On the specific problem of “many widely used libraries do not have adequate documentation / lack examples”, one thing we could do is organize a Documentation Sprint on a well-chosen week-end in the following months. People would be welcome to join in (remotely), pick a library, and start improving the documentation / writing basic examples, and we would report on our progress in a shared conversation forum (eg. a Discuss thread).


#24

Not that it’s a permanent problem, but I’ve had some trouble with odig on the Mac caused by one of the libraries it depends on. (See this bug report.) This is of course a side issue, things like ocp-browser, Tuareg, Merlin, etc. are really amazingly good tools. I miss them when working in other languages.


#25

I would happily join in on such a thing.


#26

BTW, another subtopic under documentation: mostly I’ve gotten around documentation problems to date for almost everything I’ve wanted to use. Sometimes it was suboptimal, but between the fact that OCaml code is so readable and people helping me, I’ve managed.

The exception is ppx. I know, I know, “ppx rewriters are an advanced facility, only experts really need to understand that and they do already”, etc., but the truth is, I’d like to do some hacking on some things that use ppx (like sedlex) and mostly to date I’ve been forced to thrash around and make guesses about what I’m doing. A real ppx manual, including documentation of the modern helper libraries, would be a great thing. Indeed, I think it should be part of the main OCaml manual now that ppx looks like it’s here to stay. Yes, it’s an advanced topic, but even rank amateurs like me sometimes find themselves needing to dive in.


#27

Just to make that clear, the only thing this bug prevents is apparently on macOS 10.13 to automatically open a browser tab on the package (or package index) you are interested. You can simply replace the odig doc invocation by:

open $(odig cache path)/odoc/index.html

(That said I’d still like someone to at least confirm that bug report and provide help, I currently don’t have the time to upgrade my OS).


#28

I can do that with Angstrom. I don’t know if I am competent enough to not write stupid s*t, but if someone supervises me, I’d be more than happy to participate.


#29

I agree with your claim, and don’t think it is controversial. But I would suggest to you that it works both ways, it might be causal; one way to advance in skill as an OCaml developer is to understand what senior developers observe in the current documentation that you may be missing.

Programming language popularity is a tiresome and oft-repeated argument, that I find unconvincing. For the foreseeable future, Ruby/Python will be more popular; it is by design. The features that the language developers chose were meant, in their experience, easier for beginners to do understand. In my mind, if one were to build a model of language polarity, one would have to give that factor 10x more weight than documentation, because those choices came first.

But to echo my previous point, one reason why those languages have the documentation that they do is because of the features that they lack with respect to OCaml. In the file that you linked, consider the documentation of compact. Ruby has to give the user examples because there is no way to write:

val compact: ('a, 'b option) t -> ('a, 'b) t

which has a pretty straightforward meaning. And in an immutable, typed, language really has only one thing that the function can do.

I don’t mean to distract your creative energies. But in the interest of being constructive, I think a more worth while question is how to design and write signatures that are easier to understand.


#30

So I completely understand what the type signature for compact means, but I’m not able to guess what it is used for. I bet both that I can figure it out in a few minutes, and that a line or two of documentation would obviate the need for me to try to puzzle it out.

(Note that I make no claims to being particularly good at OCaml. Also, I’m on the older side, I started with Fortran in the 1970s. Being older cuts a lot of IQ points off. But this is also why I am sensitive to points where reading the type signatures is an exercise much like solving a sudoku. I don’t mind the challenge, but I’d rather be spending that time on my code…)


#31

I completely agree. There aren’t many languages around which constantly have their de-facto standard libraries being switched and refurbrished, while staying rock solid in the process. But I think this is also a curse, because this situation makes OCaml harder to learn.

Yeah, but after just a very small mental leap you end up with this: https://github.com/inhabitedtype/angstrom/blob/master/lib/angstrom.mli#L379
Here we have one advanced and complicated thing explained with another advanced and complicated thing, whereas just a simple example would save me hours of experimentation.


#32

Thanks! ocp-browser is exactly something I wish was built into the docs.


#33

BTW, I thought about compact for a couple of minutes and I indeed can now guess what it would be used for. However, stack too many of these “just take a minute and think about it” moments together and learning a library becomes quite slow indeed. (And again, although I’m clearly slower than most of the people here, I suspect I’m more representative of what many programmers interested in adopting OCaml might be like. And let me repeat, for about the 800th time, that I really like OCaml. It’s really pleasant compared to many other alternatives I’ve tried.)


#34

This is clearly just the applicative functor operator on t. What’s the problem? Every OCaml programmer should know that.

cough cough

To be fair, no amount of documentation will help you on that one. You need concrete examples on how it’s used to understand why it’s useful.


#35

Yeah, if we do the DocJam weekend, I indent on dissecting the calculator example in the README and maybe extending it a bit. I think that would be extremely useful for future users of Angstrom and I am to some extent competent enough to explain maybe half of the library at this point.


#36

This is one of the reasons I was suggesting that documentation should have examples in line. It helps a lot.


#37

Absolutely, and I agree. What I think most libraries lack are not really text describing the functions, but small approachable examples.


#38

Bumping in case someone missed it—I think this is a brilliant idea and worth to try. If everyone agrees, perhaps we can start use this thread (or create another) to work out the details?


#39

Indeed this is a good idea. I think I would start out with the ocaml stdlib. :slight_smile:


#40

Also with regards to formatting, presentation, ui of the ocaml.org website, could this perhaps be of any value/use? https://github.com/facebook/docusaurus

This seems to be adopted by both bucklescript/reasonml already.