you can dump any AST by doing ocamlfind ppx_tools/dumpast your_file.ml

Learning how to read compiler errors is a must

I think this library did a faux pas. It shouldn't have separated the comments from the text. It's just too much of a pain to create a chapter due to this. I think it should detect, or have the user provide what type of comment is being used in a file, and extract comment from code.

The other faux pas is how the code is broken in sections, where it meets the comments. I think a better model is to calculate how many space the comment creates, and add linebreaks in the code in correct places to pad.

Currently the syntax highlighting is done via a client-side highlighter downloaded from a CDN. There are problems with this approach:

• <noscript> is not supported; text is black on black so it's not remotely readable with JavaScript disabled out of limitations or security/privacy--and if the goal is to deliver content accessibly to the most folks, then lowering requirements should be favored
• Requires trust and giving up data to a third-party CDN; should users need trust this third party when this could be vendored to first-party? (this also applies to Bootstrap, but at a minimum, at least this script includes a subresource integrity check to verify that the file is correct from a third party)
• Provided the CDN is trustworthy and delivering the same file, all users are downloading and executing the exact same highlighter code on the same code blocks which create wasteful processing on the device and also requires extra bandwidth to download and execute this

Moving syntax highlighting to the build phase would:

• transformation from blank <pre> block to highlighted is only executed once (memoized at build) emitting code with the appropriate CSS classes on the HTML
• Users do not need to trust or execute any third-party code
• Users on browsers with JavaScript missing or disabled, can still have a rich experience
• No additional data or CPU resources are used on client devices which is better for energy consumption and site responsiveness (no need to parse and then repaint)

analyze a single file without its .mli:

$ utop
# #use_output "dune ocaml top-module path/to/module.ml";;

you need to use --no-buffer otherwise it will buffer until the end of the test

cf mirage/alcotest#365

You can then declare your test and link with Alcotest:
(test (libraries alcotest …) …).

• can't construct the type manually (it's abstract)
• but you can deconstruct it (it's not fully abstract)

module M : sig type t = private { a : int } val create : unit -> t end = struct type t = { a : int } let create () = { a = 5 } end
(* let a = { M.a = 5 }  <-- not gonna work *)
let a = M.create ();;
(* val a : M.t = {M.a = 5} *)
let M.{ a = b } = a
(* val b : int = 5 *)

emphasize the fact that these terms are misleading, and that one should think about them as:

• string: immutable bytearray
• bytes: mutable bytearray

• declare recursive functions and types first
• then reuse in module
• recurse modules have some overhead with the way ocaml construct them

https://esy.sh/docs/en/getting-started.html seems like it should be best practice to create a project

printf !"%{sexp: (unit, Fp.t) Gate_spec.t list}\n" g;

and sexp_opaque and deriving sexp

try to use this web framework to serve a local page when watching: https://github.com/aantron/dream

you can do early returns in ocaml by throwing exceptions and catching them, which is what Core.with_return does

(* an example with type variables that produces a bug *)
let map (x: 'a * 'a) (f:'a -> 'b) : ('b * 'b) =
	let x1, x2 = x in	
	(f x1, x2)

gives

val map : 'b * 'b -> ('b -> 'b) -> 'b * 'b = <fun>

whereas it should be (f x1, f x2)

keeping type abstracts prevents unification, which would have had the compiler yell at us:

let map (type a b) (x: a * a) (f:a -> b) : (b * b) =
	let x1, x2 = x in	
	(f x1, x2)

gives us: Error: This expression has type a but an expression was expected of type b

Also, it's useful for GADTs (see GADT section)

Hey, I spotted a few mistakes on the page about maps (https://o1-labs.github.io/ocamlbyexample/basics-map.html)

• Maps in Core are not hashmaps, they are implemented with search trees. There are various important differences between the two, for instance in a hash table the keys must be hashable but in a search tree they need to be comparable instead. Core does have hashmaps as well in the Hashtbl module.
• "dictionnaries" has an extra n

Also, in the example code let balances = Map.empty (module String) I think it would be more idiomatic to do let balances = String.Map.empty. Many modules like String in Core have a specialised map submodule like this.