Matrix protocol in OCaml, Eio specialised
Fix all odoc documentation warnings in ocaml-matrix
Fixes for "dune build @doc-full" warnings:
- Escape @room as \@room in rooms.mli to avoid unknown tag warning
- Escape {roomId} as \{roomId\} in spaces.ml to fix bad markup
- Fix {!restore_session} -> {!with_session} in client.mli (wrong function name)
- Fix {!Matrix_id} etc. -> {!module-Id} etc. in matrix_proto.ml
- Remove open statements from matrix_event.mli and matrix_sync.mli,
using fully qualified paths (Matrix_id.User_id.t etc.) instead
- Create matrix_proto.mli that re-exports internal modules with
@canonical tags to resolve "Hidden fields" warnings
The hidden fields warnings occurred because types in .mli files
referenced Matrix_id types via open statements, but odoc couldn't
resolve these through the Matrix_proto wrapper. The fix re-exports
the internal modules so odoc can resolve type paths in documentation.
Sources used:
- ocaml-dev:ocaml-docs skill for odoc v3 reference syntax and
hidden fields resolution patterns (@canonical, module re-exports)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+65
-36
+1
-1
lib/matrix_client/client.mli
+1
-1
lib/matrix_client/client.mli
+1
-1
lib/matrix_client/rooms.mli
+1
-1
lib/matrix_client/rooms.mli
···
194
194
users_default : int;
195
195
(** Default power level for users. *)
196
196
notifications : (string * int) list;
197
-
(** Notification power levels (e.g., "room" for @room). *)
197
+
(** Notification power levels (e.g., "room" for \@room). *)
198
198
}
199
199
200
200
(** Get room power levels. *)
+1
-1
lib/matrix_client/spaces.ml
+1
-1
lib/matrix_client/spaces.ml
···
55
55
|> mem "guest_can_join" Jsont.bool ~dec_absent:false ~enc:(fun t -> t.guest_can_join)
56
56
|> finish)
57
57
58
-
(** Response from GET /_matrix/client/v1/rooms/{roomId}/hierarchy *)
58
+
(** Response from [GET /_matrix/client/v1/rooms/\{roomId\}/hierarchy]. *)
59
59
type hierarchy_response = {
60
60
rooms : space_room list;
61
61
next_batch : string option;
+20
-22
lib/matrix_proto/matrix_event.mli
+20
-22
lib/matrix_proto/matrix_event.mli
···
1
1
(** Matrix event types with JSON codecs. *)
2
2
3
-
open Matrix_id
4
-
5
3
(** {1 Timestamps} *)
6
4
7
5
module Timestamp : sig
···
17
15
type t = {
18
16
age : int64 option;
19
17
prev_content : Jsont.json option;
20
-
prev_sender : User_id.t option;
18
+
prev_sender : Matrix_id.User_id.t option;
21
19
redacted_because : Jsont.json option;
22
-
transaction_id : Transaction_id.t option;
20
+
transaction_id : Matrix_id.Transaction_id.t option;
23
21
}
24
22
val empty : t
25
23
val jsont : t Jsont.t
···
52
50
53
51
module Room_create_content : sig
54
52
type t = {
55
-
creator : User_id.t option;
53
+
creator : Matrix_id.User_id.t option;
56
54
room_version : string option;
57
55
predecessor : predecessor option;
58
56
type_ : string option;
59
57
}
60
58
and predecessor = {
61
-
room_id : Room_id.t;
62
-
event_id : Event_id.t;
59
+
room_id : Matrix_id.Room_id.t;
60
+
event_id : Matrix_id.Event_id.t;
63
61
}
64
62
val jsont : t Jsont.t
65
63
end
···
106
104
}
107
105
and allow_condition = {
108
106
type_ : string;
109
-
room_id : Room_id.t option;
107
+
room_id : Matrix_id.Room_id.t option;
110
108
}
111
109
val jsont : t Jsont.t
112
110
end
···
118
116
119
117
module Room_canonical_alias_content : sig
120
118
type t = {
121
-
alias : Room_alias.t option;
122
-
alt_aliases : Room_alias.t list option;
119
+
alias : Matrix_id.Room_alias.t option;
120
+
alt_aliases : Matrix_id.Room_alias.t list option;
123
121
}
124
122
val jsont : t Jsont.t
125
123
end
···
165
163
module Room_tombstone_content : sig
166
164
type t = {
167
165
body : string;
168
-
replacement_room : Room_id.t;
166
+
replacement_room : Matrix_id.Room_id.t;
169
167
}
170
168
val jsont : t Jsont.t
171
169
end
···
384
382
module Reaction_content : sig
385
383
type relates_to = {
386
384
rel_type : string;
387
-
event_id : Event_id.t;
385
+
event_id : Matrix_id.Event_id.t;
388
386
key : string;
389
387
}
390
388
type t = { relates_to : relates_to }
···
405
403
406
404
module Beacon_content : sig
407
405
type location = { uri : string; description : string option }
408
-
type relates_to = { rel_type : string; event_id : Event_id.t }
406
+
type relates_to = { rel_type : string; event_id : Matrix_id.Event_id.t }
409
407
type t = {
410
408
location : location;
411
409
timestamp : int64;
···
430
428
end
431
429
432
430
module Poll_response_content : sig
433
-
type relates_to = { rel_type : string; event_id : Event_id.t }
431
+
type relates_to = { rel_type : string; event_id : Matrix_id.Event_id.t }
434
432
type t = { relates_to : relates_to; answers : string list }
435
433
val jsont : t Jsont.t
436
434
end
437
435
438
436
module Poll_end_content : sig
439
-
type relates_to = { rel_type : string; event_id : Event_id.t }
437
+
type relates_to = { rel_type : string; event_id : Matrix_id.Event_id.t }
440
438
type t = { relates_to : relates_to; text : string }
441
439
val jsont : t Jsont.t
442
440
end
···
569
567
570
568
module State_event : sig
571
569
type 'content t = {
572
-
event_id : Event_id.t;
573
-
sender : User_id.t;
570
+
event_id : Matrix_id.Event_id.t;
571
+
sender : Matrix_id.User_id.t;
574
572
origin_server_ts : Timestamp.t;
575
573
state_key : string;
576
574
type_ : Event_type.t;
···
584
582
585
583
module Room_event : sig
586
584
type 'content t = {
587
-
event_id : Event_id.t;
588
-
sender : User_id.t;
585
+
event_id : Matrix_id.Event_id.t;
586
+
sender : Matrix_id.User_id.t;
589
587
origin_server_ts : Timestamp.t;
590
588
type_ : Event_type.t;
591
589
content : 'content;
···
598
596
599
597
module Raw_event : sig
600
598
type t = {
601
-
event_id : Event_id.t option;
602
-
sender : User_id.t;
599
+
event_id : Matrix_id.Event_id.t option;
600
+
sender : Matrix_id.User_id.t;
603
601
origin_server_ts : Timestamp.t;
604
602
type_ : Event_type.t;
605
603
state_key : string option;
606
604
content : Jsont.json;
607
605
unsigned : Unsigned.t option;
608
-
room_id : Room_id.t option;
606
+
room_id : Matrix_id.Room_id.t option;
609
607
}
610
608
val jsont : t Jsont.t
611
609
end
+8
-3
lib/matrix_proto/matrix_proto.ml
+8
-3
lib/matrix_proto/matrix_proto.ml
···
6
6
7
7
{1 Modules}
8
8
9
-
- {!Matrix_id}: Matrix identifiers (User_id, Room_id, Event_id, etc.)
10
-
- {!Matrix_event}: Event types and content structures
11
-
- {!Matrix_sync}: Sync API response types *)
9
+
- {!module-Id}: Matrix identifiers (User_id, Room_id, Event_id, etc.)
10
+
- {!module-Event}: Event types and content structures
11
+
- {!module-Sync}: Sync API response types *)
12
12
13
13
module Id = Matrix_id
14
14
module Event = Matrix_event
15
15
module Sync = Matrix_sync
16
+
17
+
(* Re-export internal modules for odoc resolution *)
18
+
module Matrix_id = Matrix_id
19
+
module Matrix_event = Matrix_event
20
+
module Matrix_sync = Matrix_sync
+29
lib/matrix_proto/matrix_proto.mli
+29
lib/matrix_proto/matrix_proto.mli
···
1
+
(** Matrix protocol types with JSON codecs.
2
+
3
+
This library provides comprehensive OCaml types and bidirectional JSON
4
+
codecs for the Matrix protocol. All codecs are built using the jsont
5
+
library for type-safe encoding and decoding.
6
+
7
+
{1 Modules}
8
+
9
+
- {!module-Id}: Matrix identifiers (User_id, Room_id, Event_id, etc.)
10
+
- {!module-Event}: Event types and content structures
11
+
- {!module-Sync}: Sync API response types *)
12
+
13
+
(** Matrix identifiers. *)
14
+
module Id : module type of Matrix_id
15
+
16
+
(** Matrix event types. *)
17
+
module Event : module type of Matrix_event
18
+
19
+
(** Matrix sync response types. *)
20
+
module Sync : module type of Matrix_sync
21
+
22
+
(** @canonical Matrix_proto.Id *)
23
+
module Matrix_id : module type of Matrix_id
24
+
25
+
(** @canonical Matrix_proto.Event *)
26
+
module Matrix_event : module type of Matrix_event
27
+
28
+
(** @canonical Matrix_proto.Sync *)
29
+
module Matrix_sync : module type of Matrix_sync
+5
-8
lib/matrix_proto/matrix_sync.mli
+5
-8
lib/matrix_proto/matrix_sync.mli
···
3
3
The sync API is the core of Matrix client communication. This module
4
4
provides types for the complete sync response structure. *)
5
5
6
-
open Matrix_id
7
-
open Matrix_event
8
-
9
6
(** {1 Timeline} *)
10
7
11
8
module Timeline : sig
12
9
type t = {
13
-
events : Raw_event.t list;
10
+
events : Matrix_event.Raw_event.t list;
14
11
limited : bool option;
15
12
prev_batch : string option;
16
13
}
···
34
31
(** {1 Room State} *)
35
32
36
33
module Room_state : sig
37
-
type t = { events : Raw_event.t list }
34
+
type t = { events : Matrix_event.Raw_event.t list }
38
35
val jsont : t Jsont.t
39
36
end
40
37
···
52
49
53
50
module Room_summary : sig
54
51
type t = {
55
-
heroes : User_id.t list option;
52
+
heroes : Matrix_id.User_id.t list option;
56
53
joined_member_count : int option;
57
54
invited_member_count : int option;
58
55
}
···
116
113
117
114
module Device_lists : sig
118
115
type t = {
119
-
changed : User_id.t list;
120
-
left : User_id.t list;
116
+
changed : Matrix_id.User_id.t list;
117
+
left : Matrix_id.User_id.t list;
121
118
}
122
119
val jsont : t Jsont.t
123
120
end