My biggest frustration with the Ocaml is with third-party libraries documentation. The majority of the docs are just function signatures without explanation, let alone usage examples.
The language however is quite nice and the stdlib is fairly complete.
Edit: Another problem I see is the (over?) reliance on PPX preprocessors. It does make a lot of tasks simpler, but it is too much magic for me personally.
It's funny that I could say the opposite about Rust if you asked what I enjoy most about the ecosystem - many third party libraries have outstanding documentation. Wonder why is that - in the end, it's just some folks like you and me spending their free time writing those. Why is it different for different languages then, is it the tooling like rustdoc and docs.rs or just the standards set by the community? Not sure.
I've not been deeply involved in either so take my hunch for what it is:
OCaml is an academic language like Haskell. Academics tend to neglect documentation in general, be it because what they're working on is mostly self-serving, lack of time/enthusiasm or a tinge of elitism on that "this should be obvious and if not just read the code".
Rust adherents seem to really want to take over the world and they realize that great documentation is an enabler for that.
Also the standard libraries and compiler set a pretty strong precedent.
It is a complete and up-to-date manual of the entire OCaml distribution, including executables, language, runtime, and standard library. It's rare to find modern industry-driven languages with this level of coherent documentation.
But regarding third-party library documentation, that is indeed spotty. Some people publish it, some don't. I have to reluctantly conclude it's due to a lack of tooling which automates the tedious processes.
Some of it can be driven by external factors: javascript was the only choice for an important domain for a long time.
Some if it I think is due to attractive syntax, or tooling. Python for example, horrible runtime performance, but people were drawn to it for probably syntax and tooling reasons.
Comparing Rust and OCaml:
The OCaml syntax is a bit odd. I was quite taken by F#, which is a very similar language to OCaml, but with some of the cumbersome syntax removed. F# seemed quite nice, looking at OCaml it just felt horrible and I didn't want to deal with it. In practice I know it would be fine, just like you get used to Lisp and it's parens, but there is a real psychology there that turns people away.
OCaml has good runtime performance, but its not the kind of language that will draw in C/C++ programmers or work for domains where you need C or C++ currently. Lack of multi-core is a huge turn off for a lot of people. This is the era where multi-core is our only path to more performance!
Rust syntax is a little more familiar to people, the runtime performance is top notch, very good at leveraging more cores, and maybe most importantly the community has made a concerted effort to make the language as approachable as possible. With good/friendly documentation and community. Easy install process, decent editor support, etc. Go ask a question about "Which way is faster" in a C# forum, you get a lecture about how you shouldn't worry about that. On a Rust forum you get an deep dive into performance concerns and language design. This seems to have drawn in people from communities you wouldn't expect. A low level, complicated language that Ruby and Javascript developers are drawn to? An interesting result!
> Python for example, horrible runtime performance, but people were drawn to it for probably syntax and tooling reasons.
Tooling? How so? Like the REPL? Because when I think of tooling, I think of things like IDEs, dependency management, and distribution. Python has one of those things now (IDEs/notebooks), but even that took a while, IMO.
Python is a weird case study for me. I'm not trying to flame war or anything- just pointing out my own blind spots and/or biases. But I just don't see much of anything redeeming about the language. It can be pretty easy to read, but I don't think most code I've seen actually is easy to read/follow.
I think it's worth keeping in mind that when Python got popular, there weren't options like Go or Node (or any other big player in server-side JS) that might hit different points on the performance versus ease of writing tradeoff. My understanding is that Python took off in a world where the other choices for languages were things like Perl and Java. Compared to Perl, Python does have a reputation of being much more readable, and compared to Java, it has the reputation of being much easier to write. People were attracted to the language initially for that, and then as the community grew, other benefits started appearing, like a rich ecosystem of third-party packages. Nowadays, other languages have appeared that offer different productivity tradeoffs, some with much better performance, so it's possible that Python won't be the first choice of as many people as before, but I don't think it's particularly surprising that people who have used it and been productive with it for years still continue to enjoy working in it. The experience of working in a language like Python hasn't actually gotten worse just because something like Go exists; it's just that some people who might have picked Go over Python 20 years ago picked Python back then because Go didn't exist yet.
I can't speak for others but for me it is the tooling. Knowing that I can get great online doc with a single command is a very good motivation to start writing said documentation.
I second this. I dislike the liberal usage of metaprogramming, especially in the context of a code base that you have to work on with multiple people. It adds another layer of concepts/complexity/magic that everyone in the team has to learn.
With PPX, the barrier to use metaprogramming has become lower (especially compared to camlp4), resulting in most modern Ocaml codebases depending on it. But the ergonomics of the end-to-end software delivery have not really followed: the fact that PPX's break between compiler versions means that in practice, a compiler upgrade becomes a very costly thing to do. It is difficult to make the case for this in an industrial setting, where languages with almost religious backwards compatibility are common (Java, C++, even Go). For Ocaml, it is especially sad, because the core language is already quite powerful and expressive, lowering the need for metaprogramming (imo).
For scenarios where code generation is needed, I prefer a separate code generation step, which produces explicit "standard" code (e.g. like protoc)
The language however is quite nice and the stdlib is fairly complete.
Edit: Another problem I see is the (over?) reliance on PPX preprocessors. It does make a lot of tasks simpler, but it is too much magic for me personally.