jon.recoil.org
forked from
anil.recoil.org/ocaml-imap
IMAP in OCaml
Enhance documentation with odoc extension plugins
- Convert RFC URL references to semantic @rfc tags across cookeio, imap, jmap
- Add security admonition warning to cookeio cookie documentation
- Add MSC protocol flow diagram to imap.mli showing IMAP session sequence
- Add Mermaid sequence diagram to jmap.mli showing JMAP request batching
Uses the new odoc-rfc-extension, odoc-admonition-extension, odoc-msc-extension,
and odoc-mermaid-extension plugins to generate styled, linked documentation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+23
lib/imap/imap.mli
+23
lib/imap/imap.mli
···
8
8
A comprehensive IMAP client library implementing
9
9
{{:https://datatracker.ietf.org/doc/html/rfc9051}RFC 9051 IMAP4rev2}.
10
10
11
+
{2 Protocol Flow}
12
+
13
+
A typical IMAP session follows this message sequence:
14
+
15
+
{@msc[
16
+
msc {
17
+
client, server;
18
+
19
+
server -> client [label="* OK IMAP4rev2 ready"];
20
+
client -> server [label="a001 LOGIN user pass"];
21
+
server -> client [label="a001 OK LOGIN completed"];
22
+
client -> server [label="a002 SELECT INBOX"];
23
+
server -> client [label="* 172 EXISTS"];
24
+
server -> client [label="a002 OK SELECT completed"];
25
+
client -> server [label="a003 FETCH 1:10 (ENVELOPE)"];
26
+
server -> client [label="* 1 FETCH (ENVELOPE ...)"];
27
+
server -> client [label="a003 OK FETCH completed"];
28
+
client -> server [label="a004 LOGOUT"];
29
+
server -> client [label="* BYE"];
30
+
server -> client [label="a004 OK LOGOUT completed"];
31
+
}
32
+
]}
33
+
11
34
{2 Quick Start}
12
35
13
36
{[
+3
-3
lib/imap/read.ml
+3
-3
lib/imap/read.ml
···
901
901
The thread response has a recursive structure where each thread node
902
902
can be either a message number or a nested list of children.
903
903
904
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-4> RFC 5256 Section 4 *)
904
+
@rfc 5256 Section 4 *)
905
905
906
906
(** Parse a single thread node.
907
907
···
909
909
- A message number optionally followed by children: "(n ...children...)"
910
910
- A dummy node (missing parent) starting with nested parens: "((...)...)"
911
911
912
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-4> RFC 5256 Section 4 *)
912
+
@rfc 5256 Section 4 *)
913
913
let rec thread_node r =
914
914
R.char '(' r;
915
915
match R.peek_char r with
···
1072
1072
- Thread 1: Message 2 (no children)
1073
1073
- Thread 2: Message 3 with child 6, which has children 4,23 and 44->7->96
1074
1074
1075
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-4> RFC 5256 Section 4 *)
1075
+
@rfc 5256 Section 4 *)
1076
1076
let threads = thread_children r in
1077
1077
crlf r;
1078
1078
Response.Thread threads
+3
-3
lib/imap/thread.ml
+3
-3
lib/imap/thread.ml
···
18
18
19
19
(** Threading algorithm used to organize messages into threads.
20
20
21
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-3> RFC 5256 Section 3 *)
21
+
@rfc 5256 Section 3 *)
22
22
type algorithm =
23
23
| Orderedsubject
24
24
(** ORDEREDSUBJECT algorithm (RFC 5256 Section 3.1).
···
45
45
Thread responses use a nested parenthesized structure where each
46
46
message may have zero or more child messages (replies).
47
47
48
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-4> RFC 5256 Section 4 *)
48
+
@rfc 5256 Section 4 *)
49
49
type 'a node =
50
50
| Message of 'a * 'a node list
51
51
(** A message with its sequence number or UID (depending on whether
···
64
64
to the threading algorithm (typically by date of the first message
65
65
in each thread).
66
66
67
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-4> RFC 5256 Section 4 *)
67
+
@rfc 5256 Section 4 *)
68
68
type 'a t = 'a node list
69
69
70
70
(** {1 Pretty Printers} *)
+3
-3
lib/imap/thread.mli
+3
-3
lib/imap/thread.mli
···
18
18
19
19
(** Threading algorithm used to organize messages into threads.
20
20
21
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-3> RFC 5256 Section 3 *)
21
+
@rfc 5256 Section 3 *)
22
22
type algorithm =
23
23
| Orderedsubject
24
24
(** ORDEREDSUBJECT algorithm (RFC 5256 Section 3.1).
···
45
45
Thread responses use a nested parenthesized structure where each
46
46
message may have zero or more child messages (replies).
47
47
48
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-4> RFC 5256 Section 4 *)
48
+
@rfc 5256 Section 4 *)
49
49
type 'a node =
50
50
| Message of 'a * 'a node list
51
51
(** A message with its sequence number or UID (depending on whether
···
64
64
to the threading algorithm (typically by date of the first message
65
65
in each thread).
66
66
67
-
@see <https://datatracker.ietf.org/doc/html/rfc5256#section-4> RFC 5256 Section 4 *)
67
+
@rfc 5256 Section 4 *)
68
68
type 'a t = 'a node list
69
69
70
70
(** {1 Pretty Printers} *)