this repo has no description
anil.recoil.org
1I wish to generate a set of OCaml module signatures and types (no implementations) that will type check, for an implementation of the JMAP protocol (RFC8620) and the associated email extensions (RFC8621). The code you generate should have ocamldoc that references the relevant sections of the RFC it is implementing, using <https://www.rfc-editor.org/rfc/rfc8620.html#section-1.2> as a template for the hyperlinks (replace the fragment with the appropriate section identifier). There are local copy of the specifications in the `spec/` directory in this repository. The `spec/rfc8620.txt` is the core JMAP protocol, which we are aiming to implement in OCaml code in this project. We must accurately capture the specification in the OCaml interface and never violate it without clear indication.
2
3The architecture of the modules should be one portable set that implement core JMAP (RFC8620) as an OCaml module called `Jmap` (with module aliases to the submodules that implement that). Then generate another set of modules that implement the email-specific extensions (RFC8621) including flag handling for (e.g.) Apple Mail under a module called `Jmap_email`. These should all be portable OCaml type signatures (the mli files), and then generate another module that implements the interface for a Unix implementation that uses the Unix module to perform real connections. You do not need to implement TLS support for this first iteration of the code interfaces.
4
5You should also generate a module index file called jmap.mli that explains how all the generated modules fit together, along with a sketch of some example OCaml code that uses it to connect to a JMAP server and list recent unread emails from a particular sender.
6
7When selecting dependencies, ONLY use Yojson, Uri and Unix in your type signatures aside from the OCaml standard library. The standard Hashtbl is fine for any k/v datastructures and do not use Maps or other functor applications for this. DO NOT generate any AST attributes, and do not use any PPX derivers or other syntax extensions. Just generate clean, conventional OCaml type signatures. DO NOT generate any references to Lwt or Async, and only use the Unix module to access basic network and storage functions if the standard library does not suffice.
8
9You can run commands with:
10
11- clean: `opam exec -- dune clean`
12- build: `opam exec -- dune build @check`
13- docs: `opam exec -- dune build @doc`
14- build while ignoring warnings: add `--profile=release` to the CLI to activate the profile that ignores warnings
15
16# Tips on fixing bugs
17
18If you see errors like this:
19
20```
21File "../../.jmap.objs/byte/jmap.odoc":
22Warning: Hidden fields in type 'Jmap.Email.Identity.identity_create'
23```
24
25Then examine the HTML docs built for that module. You will see that there are module references with __ in them, e.g. "Jmap__.Jmap_email_types.Email_address.t" which indicate that the module is being accessed directly instead of via the module aliases defined.
26
27## Documentation Comments
28
29When adding OCaml documentation comments, be careful about ambiguous documentation comments. If you see errors like:
30
31```
32Error (warning 50 [unexpected-docstring]): ambiguous documentation comment
33```
34
35This usually means there isn't enough whitespace between the documentation comment and the code element it's documenting. Always:
36
371. Add blank lines between consecutive documentation comments
382. Add a blank line before a documentation comment for a module/type/value declaration
393. When documenting record fields or variant constructors, place the comment after the field with at least one space
40
41Example of correct documentation spacing:
42
43```ocaml
44(** Module documentation. *)
45
46(** Value documentation. *)
47val some_value : int
48
49(** Type documentation. *)
50type t =
51 | First (** First constructor *)
52 | Second (** Second constructor *)
53
54(** Record documentation. *)
55type record = {
56 field1 : int; (** Field1 documentation *)
57 field2 : string (** Field2 documentation *)
58}
59```
60
61If in doubt, add more whitespace lines than needed - you can always clean this up later with `dune build @fmt` to get ocamlformat to sort out the whitespace properly.
62
63# Module Structure Guidelines
64
65IMPORTANT: For all modules, use a nested module structure with a canonical `type t` inside each submodule. This approach ensures consistent type naming and logical grouping of related functionality.
66
671. Top-level files should define their main types directly (e.g., `jmap_identity.mli` should define identity-related types at the top level).
68
692. Related operations or specialized subtypes should be defined in nested modules within the file:
70 ```ocaml
71 module Create : sig
72 type t (* NOT 'type create' or any other name *)
73 (* Functions operating on creation requests *)
74
75 module Response : sig
76 type t
77 (* Functions for creation responses *)
78 end
79 end
80 ```
81
823. Consistently use `type t` for the main type in each module and submodule.
83
844. Functions operating on a type should be placed in the same module as the type.
85
865. When a file is named after a concept (e.g., `jmap_identity.mli`), there's no need to have a matching nested module inside the file (e.g., `module Identity : sig...`), as the file itself represents that namespace.
87
88This structured approach promotes encapsulation, consistent type naming, and clearer organization of related functionality.
89
90# Software engineering
91
92We will go through a multi step process to build this library. We are currently at STEP 2.
93
941) we will generate OCaml interface files only, and no module implementations. The purpose here is to write and document the necessary type signatures. Once we generate these, we can check that they work with "dune build @check". Once that succeeds, we will build HTML documentation with "dune build @doc" in order to ensure the interfaces are reasonable.
95
962) once these interface files exist, we will build a series of sample binaries that will attempt to implement the JMAP protocol for some sample usecases, using only the Unix module. This binary will not fully link, but it should type check. The only linking error that we get should be from the missing Jmap library implementation.
97
983) we will calculate the dependency order for each module in the Jmap library, and work through an implementation of each one in increasing dependency order (that is, the module with the fewest dependencies should be handled first). For each module interface, we will generate a corresponding module implementation. We will also add test cases for this specific module, and update the dune files. Before proceeding to the next module, a `dune build` should be done to ensure the implementation builds and type checks as far as is possible.
99