TLDR: There should be an OCaml glossary of syntax used by advanced features, especially for punctuation-based syntax that is inherently hard to google.
When I’m working through OCaml code someone else has written, whether its source code for a library or application or something being discussed in a blog post, there’s a scenario I always dread, and that I tend to find myself in somewhat regularly (although less and less over the years): there’s some line noise special characters in the code that are impossible to google, and I can’t figure out what they do.
Off the top of my head, this has happened to me in the past with
(type t)in a parameter list → locally abstract type'a.→ explicitly polymorphic type annotationtype t.→ explicitly polymorphic locally abstract type (!)-'a|+'a→ covariant / contravariant type annotation!'a→ injectivity type annotationtype _ foo→ definition of a GADT| (* pattern *) -> .→ refutation case in match statement..|+=|'Foo|[>|[<→ stuff for extensible variants:=→ tbh I forget was this one does and it’s hard to google, thus proving my point. I think it does something with removing a type equation in an opened module.
And I may be forgetting some! In fact I haven’t included any of the weird notation that isn’t valid OCaml code but that often shows up when something doesn’t typecheck and/or in the toplevel, nor have I included any infix operators, both of which cause similar issues.
My proposal is that the official OCaml documentation (either the manual or somewhere on ocaml.org) should prominently feature a glossary page that includes all of these unsearchable symbols, explicitly names them, and links to a page explaining their usage. Technically the OCaml Language section of the OCaml manual provides something like this, but it’s really not written in a way that it would be useful for beginners, even if they knew to look there; as it says at the start of the section: “A good working knowledge of OCaml is assumed.” Stuff is written out in BNF-style grammar rather than code examples, the semantics are explained at the bottom within paragraphs of prose rather than in any structured format, and there’s not really any links to corresponding parts of the much more useful to a beginner An Introduction to OCaml section.
In my opinion, OCaml’s reliance on special characters for syntax extensions is a much bigger barrier to entry than most experienced users would realize—check any relevant forum and you’ll find lots of posts of the form “what does %syntax do in OCaml?” And yet some of these are still hard to reliably google, especially if you’re a beginner and you don’t know even basic syntax by name yet. Something like this would be really useful for a lot of people, and wouldn’t be that hard to write, especially for an MVP.
As a postscript, I also think it would be very useful if there was an index that matched plain-language descriptions of issues you might encounter in OCaml and advanced features that might solve them; I only learned about the with t := feature when browsing through the Language Extension section of the manual, but can think of a couple of times it would have come in handy in the past if I’d only known it existed. But that’s harder to write and so beyond the scope of this post.
