"OCaml -- first impressions"

I hope that’s not true. BTW, one of my biggest complaints about OCaml is the documentation. Luckily I can read the code relatively well, but I would prefer not to have to do it quite so often.

(In addition to the language itself, which I really love, one of my biggest positives about OCaml is the community, which is outstanding and friendly!)

2 Likes

I think in both the Reason and OCaml communities there are groups that strongly want better documentation. For example, one of the most prolific Reason community members, Jared Forsyth, has built a prototype Reason documentation HTML generator. Its output looks like this: https://jaredforsyth.com/reason-react/api/ReasonReact.html (repo at https://github.com/jaredly/docre ).

2 Likes

It’s not really a problem of tooling, even though ocamldoc can be improved on (see odoc). It’s a problem of actually writing the docs. Some people in the community do write excellent doc! Personally I try to write good .mli for the APi docs, and put some big picture explanations in the readme.

6 Likes

I agree with this, but with the condition of the .mli file is properly documented and posted online. I always think dbuenzli’s documentations are a pleasure to read: they’re separated into cohesive sections and have usage examples. See the docs for Jsonm for example.

1 Like

To motivate people writing better docs, why not fill issues with the projects pinpointing the parts that are hard to understand or, even better, submitting PRs with examples, additional explanations,… Knowing that other people care about your project may provide the necessary incentive to find the time to improve the documentation despite being very busy… :slight_smile:

7 Likes

I’ll also give this example of a “situation”: What is the proper way to use different libraries depending on the environment?

Seems like OCaml is in a transition regarding Num being converted into Zarith. Also jsoo has some implementation of Num and basically “no documentation” is available on how to use any of these (or at least you have to go read the docs on an older OCaml release)

When I try to search for Num I arrive here, where the header says it’s “legacy”: https://github.com/ocaml/num
When I go to Zarith, it’s assumed that I know how to use Num. When I go to JSOO, it’s assumed that I know how to use Num. It’s not easy to figure out how all these play together.

The naive reaction to something like this (if I wasn’t already used to dealing with things like this) would be:

  1. OCaml is unstable. Of course I already know that the nature of OCaml allows it to do such transitions without becoming “unstable” at all. But this wasn’t at all obvious to less experienced me. I guess to most people it means “you shouldn’t use this language”.

  2. It’s not easy to figure out how to use Big Ints and rationals at all. Especially to someone who is used to Python’s Decimal which actually “just works” and most of the time you don’t care about the underlying implementation. The README of Num points to a paper from 1992 which explains how things work in the CAML language.

Of course, I managed to do some stuff, but I am still in front of the dilemma of “WTF am I doing here”? I am a bit ashamed to ask on how to use rationals, because I’m questioning my understanding of basic CS concepts :blush:. But after my confession I’ll go forward and just ask in that topic :smiley:

2 Likes

Yeah, already started doing that fainthearthedly :slight_smile:

Arguably, that’s a little bit my fault. I assumed you already knew about Zarith/Num and that the documentation for Num was easy to find, so I didn’t really fully explained the situation. Num’s deprecation is fairly recent. I don’t agree that Zarith assumes you know about Num though, and If it does, a bug report will be welcome.

This is actually a very good case of “please report your issues”, preferably on the library’s bug tracker. :slight_smile:

1 Like

It’s both I think. The format that the current documentation is in is not very good (splitting types and functions into different pages, bad formatting, etc.) and this is a serious problem in itself. Writing documentation is, of course, also something that the community needs to encourage more. There are a number of subsystems (like the whole PPX machinery) that really need more documentation desperately.

1 Like

BTW, strong suggestion: we should start a topic just about OCaml documentation and how we might go about constructively improving it.

4 Likes

If you could suggest improvements by just going to a URL directly from the docs or the terminal that could make the docs better than all other languages pretty fast I think. All docs for all languages I’ve ever seen have way too big barriers to entry and so most people never bother.

Or if you could make suggestions just by clicking on the documentation web page…

But I still say this deserves its own topic.

We have the information from opam so this should be achievable. I think topkg may have something similar when working in a project’s source tree. Using the information from the currently installed packages to initialize a bug report sounds like a very useful addition to the OCaml tool set.

I totally agree with this. And a good illustration is a discussion I had on the reason discord recently. It is very common to see complains about ocamldoc or odor there. And people tend to think that the lack of documentation is because of ocamldoc. As if it was difficult to write doc for a module with ocamldoc. But after a few minutes of discussion, basically everyone agree that what is missing is more high level doc (like blog posts, global indications on how to use a lib,…). This is not missing because of bad tooling (who can’t host a blog post or a markdown file on github/gitlab,…?). And this can’t be solved magically by tooling.

It doesn’t mean ocamldoc/odoc shouldn’t be improved. But we shouldn’t expect too much from new tools. And we shouldn’t wait new tools to start writing resources.

2 Likes

I totally disagree with that. The next generation of IA will be able to read in libraries author’s mind (and user’s one) then will generate a perfect and complete documentation… or not. :stuck_out_tongue:

Why would you want those to be separate from the main document? I don’t think you would. If you look at something like the documentation for Ruby libraries or Python libraries, the high level summary is in the same document as the description of the individual calls.

The same page for all calls sucks quite frankly. I’m a professional Python developer and it’s the most annoying thing about Python by far. Every time I press cmd+f and type to search it jumps all over the docs and doesn’t search in the docs for the function I was looking at.

We will have to agree to disagree. I find the python docs far more usable than the OCaml documentation. I don’t understand why search wouldn’t work for you, it works fine for me on Python and Ruby pages, and I use those docs all the time. I find the OCaml docs very hard to use by contrast — they’re both badly formatted and broken up in odd ways that make reading them harder.

1 Like

(I like the Ruby docs even more, for what it’s worth.)

Call me biased, but the best documentation I’ve seen is Erlang’s. I have no idea why, and that’s despite the fact that pretty much everyone agrees that the API design is horribly inconsistent. Still, it’s extremely easy to find out how to use stuff (easier than Python) - I have programmed professionally in Erlang, Python, Elixir and JavaScript and Erlang is the best. Of course, it might be because Erlang only really supports one programming paradigm (the actor model), but does that very well, and everything is designed around it… so it’s quite obvious why you want to do stuff (after certain level of competence).

4 Likes