dev meeting 20210713

Present at the meeting:

• James Somers (@jsomers)
• Carl Eastlund (@ceastlund)
• Aaron Zeng (@bcc32)
• Guillaume Petiot (@gpetiot)
• Nathan Rebours (@NathanReb)

Current plan

• Guillaume allow configuring which server binary the ocamlformat RPC client should use via an env var
• Guillaume allow setting the configuration through the RPC protocol
• Nathan looks into whether we can allow use of labels in mli before the release of odoc 2

Meeting notes

The purpose of this meeting was to clarify a few things regarding formatting of toplevel and ocaml blocks in MDX and what was required for this to be usable internally at Jane Street.

From discussions w/ Etienne Millon, Nathan was under the impression that ocamlformat was getting close to enter a state where JS wouldn't need other formatting tools on top of it. That is true of ocp-indent but not of other tools that JS will still apply on top of ocamlformat so we do need a mechanism for JS to have custom formatting of MDX blocks.

Carl recently expressed his preference for a centralized RPC server, spawned by the build system rather than by each individual MDX processes. While we do share this preference, we agreed that it might be best to first get a working version of MDX with formatting, using the current scheme (one server per MDX process) as the performance hit didn't seem to be too much of an issue. ocamlformat's RPC would require more work to handle concurrent connections properly, especially since we'd like it to be portable accross platforms. This would delay the feature for too long. Once we have the first version working, we won't have to modify MDX for it to support this alternative architecture, everything can be done on the ocamlformat RPC side and configured via env vars without MDX needing to know anything about it.

For this first version we'll need to add a way to configure the RPC client by passing an explicit path to a binary to use as server. MDX shouldn't have to forward any kind of RPC specific configuration so we'll use an environment variable for that purpose. One can already use a custom server binary by adding it to the path with the right name but this probably won't do for JS as they might want to use different server binaries in different places and would much prefer a cleaner solution. Finally, the ocamlformat RPC protocol should allow setting the ocamlformat configuration.

Once we have both those features, JS folks will be able to write their own RPC server, wrapping ocamlformat and their other formatting tools. MDX will simply talk to it via the RPC client.

We also briefly discussed progress on the MDX labels support in mli files. A PR upgrading from odoc.parser to odoc-parser (odoc's 2.0 parser) was merged today. We're theoretically ready to add this feature but we need to look into what it means to merge it before the release of odoc.2.0. The feature is already written so, worst case scenario, we should be able to release it right after odoc 2 hits opam.