If you’re a library/tool author, please put a small code demo in the readme, or at least link to some. I’d like to see what the syntax looks like at a glance. I think it helps adoption for all projects, including this one.

I agree. It helps show off your proposed model for the problem, your priorities, and other factors like your style. I think these go a long way towards “grokking” the library.

These are a bit out of date, but they give you some flavor of the library, in an interactive form:

http://www.ujamjar.com/hardcaml/

If you're interested in understanding more about what Hardcaml is trying to achieve, you might enjoy this interview with Andy Ray, the primary author of the library:

https://signalsandthreads.com/programmable-hardware/

It's a podcast, but you can read the transcript too, if you're not into that format.

One thing that really struck me about the conversation is how much of the benefit that Andy sees coming from Hardcaml is from the testing story.

Jane Street uses this for their FPGAs. The creator of Hardcaml works there and was featured on their official podcast. https://signalsandthreads.com/programmable-hardware/

This reminds me of Handel[1], a hardware description language where you built circuits using Standard ML[2], which is similar to OCaml.

[1] No page for Handel unfortunately, but its successor Handel-C has a page: https://en.wikipedia.org/wiki/Handel-C#History

[2] https://en.wikipedia.org/wiki/Standard_ML

Does this improve on languages like VHDL and Verilog?