Documentation fixes

jonludlam · jonludlam · commit 301a62d90da4 · 2025-07-15T13:46:12.000Z
Largely these problems were found by running `odoc_driver`.

The changes to the opam files are to let docs-ci know that other
packages need to be available to build the docs correctly. Dune
will soon be able to insert these itself, but not yet.
diff --git a/doc/dune b/doc/dune
@@ -3,3 +3,29 @@
   (deps (package eio_main) (env_var "EIO_BACKEND"))
   (enabled_if (<> %{os_type} "Win32"))
   (files multicore.md))
+
+(install
+ (section doc)
+ (files
+  (odoc-config-eio.sexp as odoc-config.sexp))
+ (package eio))
+
+(install
+ (section doc)
+ (files
+  odoc-config.sexp)
+ (package eio_linux))
+
+(install
+ (section doc)
+ (files
+  odoc-config.sexp)
+ (package eio_posix))
+
+(install
+ (section doc)
+ (files
+  odoc-config.sexp)
+ (package eio_windows))
+
+
diff --git a/doc/odoc-config-eio.sexp b/doc/odoc-config-eio.sexp
@@ -0,0 +1,3 @@
+(libraries unix)
+(packages eio_main bigstring)
+
diff --git a/doc/odoc-config.sexp b/doc/odoc-config.sexp
@@ -0,0 +1,2 @@
+(packages eio_main)
+
diff --git a/eio.opam b/eio.opam
@@ -42,3 +42,7 @@ build: [
   ]
 ]
 dev-repo: "git+https://github.com/ocaml-multicore/eio.git"
+x-extra-doc-deps: [
+  "eio_main" {= version}
+  "bigstring"
+]
diff --git a/eio.opam.template b/eio.opam.template
@@ -0,0 +1,4 @@
+x-extra-doc-deps: [
+  "eio_main" {= version}
+  "bigstring"
+]
diff --git a/eio_linux.opam b/eio_linux.opam
@@ -34,3 +34,6 @@ build: [
 ]
 dev-repo: "git+https://github.com/ocaml-multicore/eio.git"
 available: [os = "linux"]
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/eio_linux.opam.template b/eio_linux.opam.template
@@ -1 +1,4 @@
 available: [os = "linux"]
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/eio_main.opam b/eio_main.opam
@@ -35,3 +35,6 @@ build: [
 ]
 dev-repo: "git+https://github.com/ocaml-multicore/eio.git"
 x-ci-accept-failures: ["macos-homebrew"]
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/eio_main.opam.template b/eio_main.opam.template
@@ -1 +1,4 @@
 x-ci-accept-failures: ["macos-homebrew"]
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/eio_posix.opam b/eio_posix.opam
@@ -31,3 +31,6 @@ build: [
   ]
 ]
 dev-repo: "git+https://github.com/ocaml-multicore/eio.git"
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/eio_posix.opam.template b/eio_posix.opam.template
@@ -0,0 +1,3 @@
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/eio_windows.opam b/eio_windows.opam
@@ -31,3 +31,6 @@ build: [
 ]
 dev-repo: "git+https://github.com/ocaml-multicore/eio.git"
 #available: [os = "win32"]
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/eio_windows.opam.template b/eio_windows.opam.template
@@ -1 +1,4 @@
 #available: [os = "win32"]
+x-extra-doc-deps: [
+  "eio_main" {= version}
+]
diff --git a/lib_eio/condition.mli b/lib_eio/condition.mli
@@ -97,7 +97,7 @@ val register_immediate : t -> (unit -> unit) -> request
     Therefore, care is needed here. This is typically used to send a wake-up event to some non-Eio library. *)
 
 val cancel : request -> bool
-(** [cancel request] tries to cancel a request created with {!register_unsafe}.
+(** [cancel request] tries to cancel a request created with {!register_immediate}.
 
     It returns [true] if the request was cancelled (the callback will never be called),
     or [false] if the request was already complete (the callback has already been called). *)
diff --git a/lib_eio/core/eio__core.mli b/lib_eio/core/eio__core.mli
@@ -382,7 +382,7 @@ module Fiber : sig
 
   val get : 'a key -> 'a option
   (** [get key] reads [key] from the map of fiber local variables, returning its
-      value or {!None} if it has not been bound. *)
+      value or [None] if it has not been bound. *)
 
   val with_binding : 'a key -> 'a -> (unit -> 'b) -> 'b
   (** [with_binding key value fn] runs [fn] with [key] bound to the provided
diff --git a/lib_eio/file.mli b/lib_eio/file.mli
@@ -29,7 +29,7 @@ module Stat : sig
   (** Kind of file from st_mode. **)
 
   val pp_kind : kind Fmt.t
-  (** Pretty printer for {! kind}. *)
+  (** Pretty printer for {!type-kind}. *)
 
   type t = {
     dev : Int64.t;              (** Device containing the filesystem where the file resides. *)
diff --git a/lib_eio/flow.mli b/lib_eio/flow.mli
@@ -127,7 +127,7 @@ module Pi : sig
     val copy : t -> src:_ source -> unit
     (** [copy t ~src] allows for optimising copy operations.
 
-        If you have no optimisations, you can use {!simple_copy} to implement this using {!single_write}. *)
+        If you have no optimisations, you can use {!Eio.Flow.Pi.simple_copy} to implement this using {!single_write}. *)
   end
 
   module type SHUTDOWN = sig
diff --git a/lib_eio/net.mli b/lib_eio/net.mli
@@ -71,7 +71,7 @@ module Ipaddr : sig
 
   (** {2 Interoperability}
 
-  To convert to or from OCaml Unix addresses, use {!Eio_unix.Ipaddr}.
+  To convert to or from OCaml Unix addresses, use {!Eio_unix.Net.Ipaddr}.
 
   To interoperate with the {{:https://opam.ocaml.org/packages/ipaddr/} ipaddr} library:
   - [Ipaddr.to_octets ipaddr_ip |> Eio.Net.Ipaddr.of_raw]
diff --git a/lib_eio/unix/eio_unix.mli b/lib_eio/unix/eio_unix.mli
@@ -101,6 +101,7 @@ module Private : sig
 
   module Rcfd = Rcfd
 
+  (** @canonical Eio_unix.Private.Fork_action *)
   module Fork_action = Fork_action
 
   module Thread_pool = Thread_pool
diff --git a/lib_eio/unix/process.mli b/lib_eio/unix/process.mli
@@ -61,7 +61,7 @@ val spawn_unix :
 (** [spawn_unix ~sw mgr ~fds args] spawns a child process running the command [args].
 
     The arguments are as for {!Eio.Process.spawn},
-    except that it takes a list of FD mappings for {!Fork_action.inherit_fds}
+    except that it takes a list of FD mappings for {!Private.Fork_action.inherit_fds}
     directly, rather than just flows for the standard streams. *)
 
 val sigchld : Eio.Condition.t
diff --git a/lib_eio_linux/low_level.mli b/lib_eio_linux/low_level.mli
@@ -109,7 +109,7 @@ val splice : fd -> dst:fd -> len:int -> int
 
     @return The number of bytes copied.
     @raise End_of_file [src] is at the end of the file.
-    @raise Unix.Unix_error(EINVAL, "splice", _) if splice is not supported for these FDs. *)
+    @raise Unix.Unix_error with args [(EINVAL, "splice", _)] if splice is not supported for these FDs. *)
 
 val connect : fd -> Unix.sockaddr -> unit
 (** [connect fd addr] attempts to connect socket [fd] to [addr]. *)

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+(libraries unix)`
	`2`	`+(packages eio_main bigstring)`
	`3`	`+`
Original file line number	Diff line number	Diff line change
`@@ -42,3 +42,7 @@ build: [`
`42`	`42`	`]`
`43`	`43`	`]`
`44`	`44`	`dev-repo: "git+https://github.com/ocaml-multicore/eio.git"`
	`45`	`+x-extra-doc-deps: [`
	`46`	`+ "eio_main" {= version}`
	`47`	`+ "bigstring"`
	`48`	`+]`
Original file line number	Diff line number	Diff line change
`@@ -34,3 +34,6 @@ build: [`
`34`	`34`	`]`
`35`	`35`	`dev-repo: "git+https://github.com/ocaml-multicore/eio.git"`
`36`	`36`	`available: [os = "linux"]`
	`37`	`+x-extra-doc-deps: [`
	`38`	`+ "eio_main" {= version}`
	`39`	`+]`
Original file line number	Diff line number	Diff line change
`@@ -35,3 +35,6 @@ build: [`
`35`	`35`	`]`
`36`	`36`	`dev-repo: "git+https://github.com/ocaml-multicore/eio.git"`
`37`	`37`	`x-ci-accept-failures: ["macos-homebrew"]`
	`38`	`+x-extra-doc-deps: [`
	`39`	`+ "eio_main" {= version}`
	`40`	`+]`
Original file line number	Diff line number	Diff line change
`@@ -31,3 +31,6 @@ build: [`
`31`	`31`	`]`
`32`	`32`	`]`
`33`	`33`	`dev-repo: "git+https://github.com/ocaml-multicore/eio.git"`
	`34`	`+x-extra-doc-deps: [`
	`35`	`+ "eio_main" {= version}`
	`36`	`+]`