In the spirit of honest and slightly frustrating reality checks, there is an interest blog post by Anders Hovmöller, OCaml — first impressions . I’ll quote the “list of reactions” below for easier commenting: Calling their REPL “toplevel” is a bit confusing The REPL needs some serious work: no…

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 …

(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 profession…

I can understand that reading an .mli file can give an understanding of what type of input i should provide to a function and what i get as an output but it hard for me to know the purpose of a function, when to use it and how to use it.

use batteries, it has an excellent documentation.

When someone publishes a library, that someone should write some working tests that can be used as usage examples. I prefer runnable code to outdated textual documentation. I did this for my dolog library: UnixJunkie/dolog/blob/master/lib_test/example.ml (* Copyright (c) 2014, INRIA. * …

Excellent example. I really like this approach over documentation because it is much faster to get my code working than reading the doc and trying to come up with code.

[image] l1x: I really like this approach over documentation It should not be an either-or problem. Lwt’s docs for instance incorporates copy-paste-and-run standalone examples along with the exact command to run it. IMO both runnable examples and documentation are equally important if we want …

"OCaml -- first impressions"

Learning

perry April 12, 2018, 12:10am 106

@airakaz See this new topic for a thread that’s just on documentation.

Topic		Replies	Views
Making OCaml Accessible and Learnable for More People Community	63	8507	December 16, 2019
OCaml at First Glance Learning	21	3640	August 30, 2022
Looking for Participants for User Survey on ocaml.org Package Documentation and Learn Area Community user-feedback , ocamlorg	37	2115	February 6, 2023
What I dislike about OCaml Community ocaml	118	13461	February 16, 2026
Why the OCaml ecosystem is poorly documented? Community	61	3402	January 29, 2025

"OCaml -- first impressions"

Related topics