In the monster thread What are the biggest reasons newcomers give up on OCaml?, @patricoferris posted a structured summary and then said the following:
Firstly, there’s actually a tremendous amount of excellent work happening (and that has happened) to improve the situation for newcomers coming to OCaml, which is great and should be celebrated! However, it probably hasn’t been communicated effectively with the broader community. […] Working out better ways to communicate that sustainably might be good.
I can’t speak for the whole tooling ecosystem for OCaml, but with my compiler contributor hat, I decided to play along and communicate on the fact that, yes, people are constantly working to improve the usability of the language implementation.
Many changes to the language and standard library participate to usability, but if we restrict to the usability of the compiler itself and its documentation, one way to see the action is to look at the compiler changelog, in particular sections “Manual and documentation” and “Compiler user-interface and warnings”.
Below are those two sections in the last two years of OCaml releases. (I trimmed some entries which I believe are less immediately related to usability.)
Working version (will become 5.1)
Manual and documentation:
#9430, #11291: Document the general desugaring rules for binding operators.
(Gabriel Scherer, review by Nicolás Ojeda Bär)#11676: Fix missing since annotation in the
SysandFormatmodules
(Github user Bukolab99, review by Florian Angeletti)Compiler user-interface and warnings:
#11679: Improve the error message about too many arguments to a function
(Jules Aguillon, review by Gabriel Scherer and Florian Angeletti)#10009: Improve the error reported by mismatched struct/sig and =/: in module
and module type bindings.
(Jules Aguillon, review by Gabriel Scherer)#11530: Include kinds in kind mismatch error message.
(Leonhard Markert, review by Gabriel Scherer and Florian Angeletti)#10818: Preserve integer literal formatting in type hint.
(Leonhard Markert, review by Gabriel Scherer and Florian Angeletti)#11338: Turn some partial application warnings into hints.
(Leo White, review by Stephen Dolan)#10931: Improve warning 14 (illegal backslash) with a better explanation
of the causes and how to fix it.
(David Allsopp, Florian Angeletti, Lucas De Angelis, Gabriel Scherer,
review by Nicolás Ojeda Bär, Florian Angeletti, David Allsopp and
Gabriel Scherer)#10911: Improve the location reported by parenthesized assert expressions
(Fabian Hemmer, review by Gabriel Scherer)#1391, #7645, #3922: Add an early error when compiling different
modules with mismatching -for-pack
(Pierre Chambart and Vincent Laviron, review by Mark Shinwell)#11297: Report “unclosed” error when “done” is missing in a “do … done”
construct.
(Nicolás Ojeda Bär)#11635, #5461, #10564: Turn warning 31 (Module_linked_twice) into a hard error
(Hugo Heuzard, review by Valentin Gatien-Baron and Gabriel Scherer)#11646: Add colors to error message hints.
(Christiana Anthony, review by Florian Angeletti)#11722: clearer error messages on non-well-founded type definitions
(Gabriel Scherer, review by Jacques Garrigue)#11235, #11864: usage warnings for constructors and fields can now be disabled
on field-by-field or constructor-by-constructor basis
(Florian Angeletti, review by Gabriel Scherer)OCaml 5.0
Manual and documentation:
#11093: Add an effect handlers tutorial
(KC Sivaramakrishnan, review by François Pottier, Gabriel Scherer, François
Bobot and Wiktor Kuchta)#11192: Better documentation for condition variables.
(François Pottier, review by Luc Maranget, Xavier Leroy, and Wiktor Kuchta)#11093: Add tutorials on parallelism features and the relaxed memory model
(KC Sivaramakrishnan, review by Damien Doligez, Anil Madhavapeddy, Gabriel
Scherer, Thomas Leonard, Tom Ridge, Xavier Leroy, Luc Maranget, Fabrice
Buoro, Olivier Nicole, Guillaume Munch-Maccagnoni, Jacques-Henri Jourdan)#11640, #11647: Add missing options to the man pages:
flambda commonly-used options, and negative options (-no-rectypes, … ).
(Amandine Nangah, review by David Allsopp, Florian Angeletti,
Sébastien Hinderer, and Vincent Laviron)#11813: Make new multicore chapters easier to discover, and emphasize impact
on C bindings.
(Edwin Török, review by KC Sivaramakrishnan, and Florian Angeletti)Compiler user-interface and warnings:
- #11089: Add ‘since ’ information to compiler warnings.
(André Maroneze, review by Florian Angeletti and Gabriel Scherer)OCaml 4.14.0 (28 March 2022)
Manual and documentation:
#7179, #11894: correct the description of CAMLreturn and CAMLreturn0 in
the Interfacing C page and memory.h file.
(Dong An, review by Guillaume Munch-Maccagnoni and Olivier Nicole )#7812, #10475: reworded the description of the behaviors of
float->int conversions in case of overflow, and of iterators
in case of concurrent modifications.
(Xavier Leroy, report by whitequark, review by David Allsopp)#8697, #10666: add M, m, n options of the OCAMLRUNPARAM to manual and man page
for ocamlrun command line options
(Dong An and Anukriti Kumar, review by David Allsopp, Gabriel Scherer
and Damien Doligez)#10281, #10685: Add description of C compiler on macOS and Windows platforms.
(Dong An, review by Xavier Leroy and David Allsopp)#10397: Document exceptions raised by Unix module functions on Windows
(Martin Jambon, review by Daniel Bünzli, David Alsopp, Damien Doligez,
Xavier Leroy, and Florian Angeletti)#10589: Fix many typos (excess/inconsistent spaces) in the HTML manual.
(Wiktor Kuchta, review by Florian Angeletti)#10605: manual, name few css classes to ease styling and maintainability.
(Florian Angeletti, review by Wiktor Kuchta and Gabriel Scherer)#10671, #10672: webman: Fix misalignments in unordered lists by changing the
CSS for coloring bullets
(Wiktor Kuchta, review by Florian Angeletti)#11120, #11133: man pages, add missing warning entries and add mnemonic names
to the list of warnings.
(Florian Angeletti, report by Kate Deplaix, review by Gabriel Scherer)Compiler user-interface and warnings:
#10328, #10780: Give more precise error when disambiguation could not
possibly work.
(Leo White, review by Gabriel Scherer and Florian Angeletti)#10361: Improve error messages for mismatched record and variant
definitions.
(Florian Angeletti, review by Gabriel Radanne and Gabriel Scherer)#10407: Produce more detailed error messages that contain full error traces
when module inclusion fails.
(Antal Spector-Zabusky, review by Florian Angeletti)#9116, #9118, #10582: Fix single-line source highlighting in the
presence of tabs
(Armaël Guéneau, review by Gabriel Scherer,
split off from #9118 by Kate Deplaix, report by Ricardo M. Correia)#10488: Improve type variable name generation and recursive type detection
when printing type errors; this ensures that the names given to type variables
are always reused in the following portion of the trace and also removes
spuriousas 'as in types.
(Antal Spector-Zabusky, review by Florian Angeletti)#10794: Clarify warning 57 (Ambiguous or-pattern variables under guard)
(Wiktor Kuchta, review by Gabriel Scherer)OCaml 4.13.0 (24 September 2021)
Compiler user-interface and warnings (highlights):
- #9331: Improve error messages for functor application and functor types.
(Florian Angeletti and Gabriel Radanne, review by Leo White)
- [breaking change] #10118, #10140: enable warning 6 [labels-omitted] by default.
The following now warns:
let f ~x y = … in f 3 5
the callsite (f 3 5) has to be turned into (f ~x:3 5).
This prevents mistakes where two arguments of the same types are swapped.
(Note: Dune already enables this warning by default.)
(Gabriel Scherer, review by Xavier Leroy and Florian Angeletti,
report by ygrek)Manual and documentation (highlights):
- #10247: Add initial tranche of examples to reference manual.
Adds some eighty examples to the reference manual, principally to the
expressions and patterns sections.
OCaml - The OCaml language
(John Whitington, review by Xavier Leroy, Gabriel Scherer, @Fourchaux, and
Florian Angeletti)Manual and documentation:
#9525, #10402: document that ocamldoc only creates paragraphs
at the toplevel of documentation comments
(Florian Angeletti, report by Hendrik Tews, review by Gabriel Scherer)#10206: Split labels and polymorphic variants tutorials in two.
Moves the GADTs tutorial from the Language Extensions chapter
to the tutorials.
(John Whitington, review by Florian Angeletti and Xavier Leroy)#9786, #10181: improved documentation of Unix.{in,out}_channel_of_descr
with respect to closing.
(Xavier Leroy, report by Jacques-Henri Jourdan, review by Guillaume
Munch-Maccagnoni, Gabriel Scherer, Jacques-Henri Jourdan)#10139: Use the new -nonavbar option to improve navigation within
the reference manual stdlib documentation.
(John Whitington, review by David Allsopp)#1351: Document
-output-complete-objoption in the manual.
(François Bobot, Nicolás Ojeda Bär, review by Daniel Bünzli and Damien
Doligez)#9632: Document incremental build solutions with opam
(Vincent Laviron, review by Daniel Bünzli and Gabriel Scherer)#10497: Styling changes in the post-processed HTML manual (webman)
(Wiktor Kuchta, review by Florian Angeletti)#10605: manual, name few css classes to ease styling and maintainability.
(Florian Angeletti, review by Wiktor Kuchta and Gabriel Scherer)Compiler user-interface and warnings:
#1737, #2092, #7852, #7859, #10405, #10417: Update locations during
destructive substitutions
(Thomas Refis, review by Gabriel Radanne, report by Hugo Heuzard)#2245: Improve error message for link order error in bytecode
(Pierre Chambart, review by Jérémie Dimino and Gabriel Scherer)#8732, improved error messages for invalid private row type definitions.
For instance, [ type t = private [<A >A ] ] .
(Florian Angeletti, review by Jacques Garrigue, Thomas Refis,
and Gabriel Scherer)#9407: optional warning for missing mli interface file
(Anukriti Kumar, review by Florian Angeletti)#9960, #10619: extend ocamlc/ocamlopt’s -o option to work when
compiling C files
(Sébastien Hinderer, reported by Daniel Bünzli, review by
Florian Angeletti and Gabriel Scherer)#10095: minor simplifications to some syntax error messages.
(François Pottier, review by Gabriel Scherer and Frédéric Bour.)#10196, #10197: better error message on empty character literals ‘’.
(Gabriel Scherer, review by David Allsopp and Florian Angeletti
and Daniel Bünzli, report by Robin Björklin)#10207, #10312: deprecate consecutive letters in warning
specifications.
The form-w aBcDwas equivalent to-w -a+b-c+d.
It is now deprecated to improve the coexistence with warning mnemonics.
However, using isolated single letter is not deprecated to allow the form
-w "A-32..50-45".
(Florian Angeletti, review by Damien Doligez and Gabriel Scherer)#10232: Warning for unused record fields.
(Leo White, review by Florian Angeletti)OCaml 4.12.0 (24 February 2021)
Compiler user-interface and warnings (highlights):
- #9657: Warnings can now be referred to by their mnemonic name. The names are
displayed using-warn-helpand can be utilized anywhere where a warning list
specification is expected.
ocamlc -w +fragile-match
…[@@ocaml.warning “-fragile-match”]
Note that only a single warning name at a time is supported for now:
“-w +foo-bar” does not work, you must use “-w +foo -w -bar”.
(Nicolás Ojeda Bär, review by Gabriel Scherer, Florian Angeletti and
Leo White)Manual and documentation (highlights):
#9755: Manual: post-processing the html generated by ocamldoc and
hevea. Improvements on design and navigation, including a mobile
version, and a quick-search functionality for the API.
(San Vũ Ngọc, review by David Allsopp and Florian Angeletti)#9468: HACKING.adoc: using dune to get merlin support
(Thomas Refis, review by Gabriel Scherer)#9684: document in address_class.h the runtime value model in
naked-pointers and no-naked-pointers mode
(Xavier Leroy and Gabriel Scherer)Manual and documentation:
#10142, #10154: improved rendering and latex code for toplevel code examples.
(Florian Angeletti, report by John Whitington, review by Gabriel Scherer)#9745: Manual: Standard Library labeled and unlabeled documentation unified
(John Whitington, review by Nicolás Ojeda Bär, David Allsopp,
Thomas Refis, and Florian Angeletti)#9877: manual, warn that multi-index indexing operators should be defined in
conjunction of single-index ones.
(Florian Angeletti, review by Hezekiah M. Carty, Gabriel Scherer,
and Marcello Seri)#10233: Document
-save-ir-after schedulingand update-stop-afteroptions.
(Greta Yorsh, review by Gabriel Scherer and Florian Angeletti)Compiler user-interface and warnings:
- [breaking change] #9011: Do not create .a/.lib files when creating a .cmxa with no modules.
macOS ar doesn’t support creating empty .a files (#1094) and MSVC doesn’t
permit .lib files to contain no objects. When linking with a .cmxa containing
no modules, it is now not an error for there to be no .a/.lib file.
(David Allsopp, review by Xavier Leroy)
#9560: Report partial application warnings on type errors in applications.
(Stephen Dolan, report and testcase by whitequark, review by Gabriel Scherer
and Thomas Refis)#9583: when bytecode linking fails due to an unavailable module, the module
that requires it is now included in the error message.
(Nicolás Ojeda Bär, review by Vincent Laviron)#6633, #9673: Add hint when a module is used instead of a module type or
when a module type is used instead of a module or when a class type is used
instead of a class.
(Xavier Van de Woestyne, report by whitequark, review by Florian Angeletti
and Gabriel Scherer)#9754: allow [@tailcall true] (equivalent to [@tailcall]) and
[@tailcall false] (warns if on a tailcall)
(Gabriel Scherer, review by Nicolás Ojeda Bär)#9751: Add warning 68. Pattern-matching depending on mutable state
prevents the remaining arguments from being uncurried.
(Hugo Heuzard, review by Leo White)#9783: Widen warning 16 (Unerasable optional argument) to more cases.
(Leo White, review by Florian Angeletti)#10008: Improve error message for aliases to the current compilation unit.
(Leo White, review by Gabriel Scherer)#10046: Link all DLLs with -static-libgcc on mingw32 to prevent dependency
on libgcc_s_sjlj-1.dll with mingw-w64 runtime 8.0.0 (previously this was
only needed for dllunix.dll).
(David Allsopp, report by Andreas Hauptmann, review by Xavier Leroy)#9634: Allow initial and repeated commas in
OCAMLRUNPARAM.
(Nicolás Ojeda Bär, review by Gabriel Scherer)