OCaml has better than that: it has (sadly underused, despite having a trivial deployement story) .mld files which allow you to write documentation about your APIs with checked cross-references into your APIs.
Here are a couple of references to different manuals written with .mld files: vg, brr, jsont, bytesrw, cmdliner.
That’s super cool! Rust’s mdBook has something similar. Is there a mld tutorial that I could check out? I see this page but it’s a little bare bones for my taste.
Not that I’m aware of.
But basically a .mld page is just the ocamldoc language that you write in .mli files without the OCaml comments (** *).
Here is a minimal .mld file:
{0 Hello doc}
I'm your first paragraph.
{1:first I'm your first section}
I'm your first paragraph of your first section.
For building them if you are using dune I guess these are the runes (not using dune so someone else may know better).
Sounds great! I can look into writing a tutorial or figuring out ways to make it more common for packages.
This is 100% correct. A good while ago I raised an issue with Jane Street for adding support for some sort of raw string literals in their s-expression format. Probably not for printing them back out, but certainly for parsing them. I asked themIf they would accept such a change if someone were to contribute it. This is a blindingly obvious thing to want if you’re going to use ss-expressions for any sort of configuration files. I mean, it’s just blisteringly obvious only an idiot would think otherwise.
Which is why it’s so great that they basically said nope we’re not going to do it.
Having maintainers that robustly say “no” to bad ideas like the above is why I gratefully enjoy using @dbuenzli’s and Jane Street’s libraries and Lwt/Mirage, usually in different industrial and research contexts.
If I want portable libraries for projects that need to be “Unix-style”, I usually pick Daniel’s software stack. If I need something portable that’s heading for the web then Lwt (and more recently Eio) is a good choice. If I need a library for a larger IO-heavy system that need more batteries included, I usually go for Async.
I note that many years after our experience report on Xen/OCaml, the xapi project is still going strong today since 2005 by building over Threads and Lwt. It’s a testament to how rock solid the OCaml ecosystem is that a project like this can evolve over two decades without any significant breakage. Similar story for liquidsoap.
I think the reason for this is the flexibility afforded by having different basis libraries that share a common programming language, but don’t need to walk over each other and can evolve separately. I agree it makes learning the language more difficult for newcomers, but that’s primarily because more books like RWO don’t exist for the language.
I’d be delighted, for example, to see a tome on “Daniel’s recipe book for delicious OCaml programs” emerge. And that doesn’t need to be written by Daniel if he doesn’t have time, but by a motivated user of his code.
y’know what, nevermind. I don’t have any interest in arguing this point. Not like it’s gonna change what those HFT jocks at Jane Street do anyway.
Building on what @avsm is saying, one of the patterns that I’m seeing in these discussions is different meanings of “documentation.” Documentation of type signatures/APIs is one thing, and something I think the OCaml community does pretty well. But indeed we generally don’t yet have “Daniel’s Delicious Recipes,” and similar efforts.
I think @NicholasLYang desires more explanatory documentation (maybe also more tutorials, I’m not sure). Explanatory documentation would be more along the lines of “Functional Programming with OCaml.” Documentation that explains the FP paradigm and practices. We have some of this but not a ton and, all else being equal, more would be better.
When I was starting out, I relied a lot on SML texts to help me understand functional programming, using ML syntax. Things are indeed better today—e.g., the CS3110 text—but more foundational discussions would be lovely.
Yeah, agreed on more explanatory and tutorial based documentation. Maybe not necessarily for functional programming, since I think that’s a well covered area, but for building stuff like a CLI or a web server. In my experience, a lot of functional languages will teach you monads and type theory before they teach you the more mundane stuff like writing a file or making a web server. The former is great if that’s your jam, but I think a lot of people want to do stuff with a language and want to start from that perspective.
For example, I started learning Rust by reading Programming Rust (not to be confused with The Rust Programming Language), which starts with a quick tutorial on how to build a fractal generator. I just typed along to the tutorial, built the code, and had a holy crap moment when the thing ran and I saw some pretty fractals. It felt good and it gave me an immediate idea of how to do something in Rust.
Whereas when I tried to learn Haskell, I remember looking up some web libraries and the tutorial was just an explanation about how the core type is a monad, and a few type signatures. I imagine stuff has gotten way better since then, but it just didn’t have the same level of explanation. Even the books I read spent more time on monads and functors than on how to build anything substantial.
Just a reminder… Looking for Maintainers / Moderators for the OCaml Cookbook
490 messages and counting.
I wonder if the list maintainers could create “perennial topics” like “docs suck” or “stdlib stinketh” etc. for the complaints that get repeated repeatedly.
The point of this topic, afaik, is to gather input from people who struggle to get into OCaml, so that we, as a community, can support them and incorporate their input and energies to improve the experience of newcomers.
It seems natural that different people will continue to struggle with the same kind of hurdles, even as we improve them, so it is also expected that we’d get new perspectives or updated reports about the same topics.
These are generally offered here in the spirit of useful critical feedback, not complaints, and the people graciously take their time to share are helping us. I think it is important that we continue to offer safe and welcoming places for such feedback and for open discussions about how to address it.
To that end, I would encourage established members of the community not to denigrate or belittle that activity.
With reference to some earlier comments by others, I also suggest that we keep this kind of topic constructive and focused on the topic at hand and not use it for airing unrelated feuds or gripes (which, IMO, are better addressed in separate topics or in more direct communications).
In my experience having high level tracking issues on the GitHub repo could help, something like “Stdlib Improvements”, with sub issues underneath it. If a user wants to report a potential improvement, they can link their issue with the top level one. And if someone comes in with a generic complaint, contributors can direct them to the top level issue and encourage them to contribute.
I am toying with the idea of experimenting with OCaml again. So, if the circumstances permit, I may provide more concrete feedback.