This is my third time trying to learn OCaml and this time I think I succeeded to go “beyond the point of no-return” (I am sold and will build software in OCaml). I managed to write a non-trivial thing - a parser using Angstrom.
At this point I think this state of affairs is the single biggest shortcoming of the language/community. I don’t know if it’s me (that I’m not super intelligent) but reading type signatures is a real struggle for me, in order to get the “bigger picture”. On the other hand the OCaml community seems “in agreement” that having a .mli file is enough of a documentation. At least that’s the impression I get from the several dozens of libraries I researched with regards of my project.
It’s far from perfect, but we’re trying to make things better for the libraries we release, especially the most fundamental ones. Here are some examples:
far from perfect, but a lot more than just type signatures. And my hope is that documentation will continue to get better in the next year or two. Certainly we’re planning on continuing to work on it at Jane Street.
Of course, having this forum and also the nice folks in the ReasonML discord server were certainly the things that made all the difference on my third attempt, for it to become successful. Both were not available on my previous attempt several years ago. And actually maybe the reason for my decision to give it another go was the fact that I found out the forum.
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!)
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 ).
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.
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.
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…
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:
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”.
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 . But after my confession I’ll go forward and just ask in that topic
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.
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.
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.
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.
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.
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.
. But after my confession I’ll go forward and just ask in that topic 
