Documentation fixes: cross-refs, internal links

CHANGES

@@ -14,13 +14,13 @@
 
   * On Windows, make Lwt_process.create_process duplicate standard handles given to the child process if they're not inheritable, to mimic the behaviour of Unix.create_process. (#909, Antonin Décimo)
   * Add missing dependency to `cppo` in lwt-react's opam file. (#946, Rizo I)
+  * Improve documentation (especially internal links). (#928, Antonin Décimo)
 
 ====== Fixes ======
 
   * Fix win32_spawn leaking dev_null fd in the parent process. (#906, Antonin Décimo)
   * Prefer SetHandleInformation to DuplicateHandle in set_close_on_exec for sockets. DuplicateHandle mustn't be used on sockets. (#907, Antonin Décimo)
-  * Lwt.pick and Lwt.choose select preferentially failed promises as per
-  documentation (#856, #874, Raman Varabets)
+  * Lwt.pick and Lwt.choose select preferentially failed promises as per documentation (#856, #874, Raman Varabets)
   * Use the WSA_FLAG_NO_HANDLE_INHERIT on Windows when creating sockets with WSASocket if the cloexec (non-inheritable) parameter is true. Fixes a Windows problem where a child process would inherit a supposedly non-inheritable socket. (#910, Antonin Décimo)
   * Fix macOS/arm64 tests which have a 16k page. (#932, Kate Deplaix)
 

src/core/lwt_mvar.mli

@@ -28,7 +28,7 @@
 
 (** Mailbox variables *)
 
-(** "Mailbox" variables implement a synchronising variable, used for
+(** “Mailbox” variables implement a synchronising variable, used for
     communication between concurrent threads. *)
 
 type 'a t

src/core/lwt_pqueue.mli

@@ -6,11 +6,11 @@
 (** Functional priority queues (deprecated).
 
     A priority queue maintains, in the abstract sense, a set of elements in
-    order, and supports fast lookup and removal of the first ("minimum")
+    order, and supports fast lookup and removal of the first (“minimum”)
     element. This is used in Lwt for organizing threads that are waiting for
     timeouts.
 
-    The priority queues in this module preserve "duplicates": elements that
+    The priority queues in this module preserve “duplicates”: elements that
     compare equal in their order.
 
     @deprecated This module is an internal implementation detail of Lwt, and may

src/core/lwt_stream.mli

@@ -45,10 +45,8 @@ val create : unit -> 'a t * ('a option -> unit)
 (** [create ()] returns a new stream and a push function.
 
     To notify the stream's consumer of errors, either use a separate
-    communication channel, or use a
-    {{:https://ocaml.org/api/Stdlib.html#TYPEresult}
-    [result]} stream. There is no way to push an exception into a
-    push-stream. *)
+    communication channel, or use a {!Stdlib.result} stream. There is
+    no way to push an exception into a push-stream. *)
 
 val create_with_reference : unit -> 'a t * ('a option -> unit) * ('b -> unit)
 (** [create_with_reference ()] returns a new stream and a push
@@ -78,22 +76,22 @@ class type ['a] bounded_push = object
   (** Change the size of the stream queue. Note that the new size
       can smaller than the current stream queue size.
 
-      It raises [Invalid_argument] if [size < 0]. *)
+      It raises {!Stdlib.Invalid_argument} if [size < 0]. *)
 
   method push : 'a -> unit Lwt.t
   (** Pushes a new element to the stream. If the stream is full then
       it will block until one element is consumed. If another thread
-      is already blocked on {!push}, it raises {!Full}. *)
+      is already blocked on [push], it raises {!Lwt_stream.Full}. *)
 
   method close : unit
-  (** Closes the stream. Any thread currently blocked on {!push}
-      fails with {!Closed}. *)
+  (** Closes the stream. Any thread currently blocked on
+      {!Lwt_stream.bounded_push.push} fails with {!Lwt_stream.Closed}. *)
 
   method count : int
   (** Number of elements in the stream queue. *)
 
   method blocked : bool
-  (** Is a thread is blocked on {!push} ? *)
+  (** Is a thread is blocked on {!Lwt_stream.bounded_push.push} ? *)
 
   method closed : bool
   (** Is the stream closed ? *)
@@ -238,11 +236,7 @@ val junk_while_s : ('a -> bool Lwt.t) -> 'a t -> unit Lwt.t
 
 val junk_old : 'a t -> unit Lwt.t
 (** [junk_old st] removes all elements that are ready to be read
-    without yielding from [st].
-
-    For example, the [read_password] function of [Lwt_read_line]
-    uses it to flush keys previously typed by the user.
-*)
+    without yielding from [st]. *)
 
 val get_available : 'a t -> 'a list
 (** [get_available st] returns all available elements of [l] without
@@ -397,7 +391,11 @@ val hexdump : char t -> string t
     Basically, here is a simple implementation of [hexdump -C]:
 
     {[
-      let () = Lwt_main.run (Lwt_io.write_lines Lwt_io.stdout (Lwt_stream.hexdump (Lwt_io.read_lines Lwt_io.stdin)))
+      let () = Lwt_main.run begin
+          Lwt_io.write_lines
+            Lwt_io.stdout
+            (Lwt_stream.hexdump (Lwt_io.read_lines Lwt_io.stdin))
+        end
     ]}
 *)
 

src/react/lwt_react.mli

@@ -31,7 +31,7 @@ module E : sig
   val next : 'a event -> 'a Lwt.t
   (** [next e] returns the next occurrence of [e].
 
-      Avoid trying to create an "asynchronous loop" by calling [next e] again in
+      Avoid trying to create an “asynchronous loop” by calling [next e] again in
       a callback attached to the promise returned by [next e]:
 
       - The callback is called within the React update step, so calling [next e]
@@ -40,7 +40,7 @@ module E : sig
       - If you instead arrange for the React update step to end (for example, by
         calling [Lwt.pause ()] within the callback), multiple React update steps
         may occur before the callback calls [next e] again, so some occurrences
-        can be effectively "lost."
+        can be effectively “lost.”
 
       To robustly asynchronously process occurrences of [e] in a loop, use
       [to_stream e], and repeatedly call {!Lwt_stream.next} on the resulting
@@ -66,7 +66,7 @@ module E : sig
         value is available on the stream.
 
         If updating the event causes an exception at any point during the update
-        step, the excpetion is passed to [!]{!Lwt.async_exception_hook}, which
+        step, the exception is passed to [!]{!Lwt.async_exception_hook}, which
         terminates the process by default. *)
 
   val delay : 'a event Lwt.t -> 'a event

src/unix/config/discover.ml

@@ -463,10 +463,10 @@ struct
            linking with -lpthread fails. So, try to link the test code without
            any flags first.
 
-           If that fails and we are not targetting Android, try to link with
+           If that fails and we are not targeting Android, try to link with
            -lpthread. If *that* fails, search for libpthread in the filesystem.
 
-           When targetting Android, compiling without -lpthread is the only way
+           When targeting Android, compiling without -lpthread is the only way
            to link with pthread, and we don't to search for libpthread, because
            if we find it, it is likely the host's libpthread. *)
         match compiles context code with

src/unix/lwt_engine.mli

@@ -144,7 +144,7 @@ class libev : ?backend:Ev_backend.t -> unit -> object
     (** Returns [loop]. *)
 end
 
-(** Engine based on [Unix.select]. *)
+(** Engine based on {!Unix.select}. *)
 class select : t
 
 (** Abstract class for engines based on a select-like function. *)

src/unix/lwt_fmt.mli

@@ -7,26 +7,21 @@
 
     @since 4.1.0 *)
 
-(** This module bridges the gap between
-    {{:https://ocaml.org/api/Format.html} [Format]}
-    and {!Lwt}. Although it is not required, it is recommended to use this
-    module with the {{:http://erratique.ch/software/fmt} [Fmt]} library.
+(** This module bridges the gap between {!Stdlib.Format} and {!Lwt}.
+    Although it is not required, it is recommended to use this module
+    with the {{:http://erratique.ch/software/fmt} [Fmt]} library.
 
     Compared to regular formatting function, the main difference is that
     printing statements will now return promises instead of blocking.
 *)
 
 val printf : ('a, Format.formatter, unit, unit Lwt.t) format4 -> 'a
 (** Returns a promise that prints on the standard output.
-    Similar to
-    {{:https://ocaml.org/api/Format.html#VALprintf}
-    [Format.printf]}. *)
+    Similar to {!Stdlib.Format.printf}. *)
 
 val eprintf : ('a, Format.formatter, unit, unit Lwt.t) format4 -> 'a
 (** Returns a promise that prints on the standard error.
-    Similar to
-    {{:https://ocaml.org/api/Format.html#VALeprintf}
-    [Format.eprintf]}. *)
+    Similar to {!Stdlib.Format.eprintf}. *)
 
 (** {1 Formatters} *)
 
@@ -55,16 +50,14 @@ val stderr : formatter
 val make_formatter :
   commit:(unit -> unit Lwt.t) -> fmt:Format.formatter -> unit -> formatter
 (** [make_formatter ~commit ~fmt] creates a new lwt formatter based on the
-    {{:https://ocaml.org/api/Format.html#TYPEformatter}
-    [Format.formatter]} [fmt]. The [commit] function will be called by the
+    {!Stdlib.Format.formatter} [fmt]. The [commit] function will be called by the
     printing functions to update the underlying channel.
 *)
 
 val get_formatter : formatter -> Format.formatter
-(** [get_formatter fmt] returns the underlying
-    {{:https://ocaml.org/api/Format.html#TYPEformatter}
-    [Format.formatter]}. To access the underlying formatter during printing, it
-    isvrecommended to use [%t] and [%a].
+(** [get_formatter fmt] returns the underlying {!Stdlib.Format.formatter}.
+    To access the underlying formatter during printing, it
+    is recommended to use [%t] and [%a].
 *)
 
 (** {2 Printing} *)
@@ -82,10 +75,8 @@ val ikfprintf :
   formatter -> ('b, Format.formatter, unit, 'a) format4 -> 'b
 
 val flush : formatter -> unit Lwt.t
-(** [flush fmt] flushes the formatter (as with
-    {{:https://ocaml.org/api/Format.html#VALpp_print_flush}
-    [Format.pp_print_flush]}) and
-    executes all the printing action on the underlying channel.
+(** [flush fmt] flushes the formatter (as with {!Stdlib.Format.pp_print_flush})
+    and executes all the printing action on the underlying channel.
 *)
 
 

src/unix/lwt_io.mli

@@ -28,7 +28,7 @@
     Note about errors: input functions of this module raise
     [End_of_file] when the end-of-file is reached (i.e. when the read
     function returns [0]). Other exceptions are ones caused by the
-    backend read/write functions, such as [Unix.Unix_error].
+    backend read/write functions, such as {!Unix.Unix_error}.
 *)
 
 exception Channel_closed of string
@@ -118,7 +118,7 @@ val make :
       @param close close function of the channel. It defaults to
       [Lwt.return]
 
-      @param seek same meaning as [Unix.lseek]
+      @param seek same meaning as {!Unix.lseek}
 
       @param mode either {!input} or {!output}
 
@@ -275,17 +275,15 @@ val read_into_exactly_bigstring : input_channel -> Lwt_bytes.t -> int -> int ->
 
 val read_value : input_channel -> 'a Lwt.t
 (** [read_value channel] reads a marshaled value from [channel]; it corresponds
-    to the standard library's
-    {{:https://ocaml.org/api/Marshal.html#VALfrom_channel} [Marshal.from_channel]}.
-    The corresponding writing function is {!write_value}.
+    to the standard library's {!Stdlib.Marshal.from_channel}. The corresponding
+    writing function is {!write_value}.
 
     Note that reading marshaled values is {e not}, in general, type-safe. See
-    the warning in the description of module
-    {{:https://ocaml.org/api/Marshal.html}
-    [Marshal]} for details. The short version is: if you read a value of one
-    type, such as [string], when a value of another type, such as [int] has
-    actually been marshaled to [channel], you may get arbitrary behavior,
-    including segmentation faults, access violations, security bugs, etc. *)
+    the warning in the description of module {!Stdlib.Marshal} for details. The
+    short version is: if you read a value of one type, such as [string], when a
+    value of another type, such as [int] has actually been marshaled to
+    [channel], you may get arbitrary behavior, including segmentation faults,
+    access violations, security bugs, etc. *)
 
 (** {2 Writing} *)
 
@@ -336,9 +334,8 @@ val write_from_string_exactly :
 val write_value :
   output_channel -> ?flags : Marshal.extern_flags list -> 'a -> unit Lwt.t
 (** [write_value channel ?flags v] writes [v] to [channel] using the [Marshal]
-    module of the standard library. See
-    {{:https://ocaml.org/api/Marshal.html#VALto_channel}
-    [Marshal.to_channel]} for an explanation of [?flags].
+    module of the standard library. See {!Stdlib.Marshal.to_channel} for an
+    explanation of [?flags].
 
     The corresponding reading function is {!read_value}. See warnings about type
     safety in the description of {!read_value}. *)
@@ -421,8 +418,7 @@ val open_file :
     If [~buffer] is supplied, it is used as the I/O buffer.
 
     If [~flags] is supplied, the file is opened with the given flags (see
-    {{: https://ocaml.org/api/Unix.html#TYPEopen_flag}
-    [Unix.open_flag]}). Note that [~flags] is used {e exactly} as given. For
+    {!Unix.open_flag}). Note that [~flags] is used {e exactly} as given. For
     example, opening a file with [~flags] and [~mode:Input] does {e not}
     implicitly add [O_RDONLY]. So, you should include [O_RDONLY] when opening
     for reading ([~mode:Input]), and [O_WRONLY] when opening for writing
@@ -436,7 +432,7 @@ val open_file :
     Note: if opening for writing ([~mode:Output]), and the file already exists,
     [open_file] truncates (clears) the file by default. If you would like to
     keep the pre-existing contents of the file, use the [~flags] parameter to
-    pass a custom flags list that does not include [Unix.O_TRUNC].
+    pass a custom flags list that does not include {!Unix.O_TRUNC}.
 
     @raise Unix.Unix_error on error. *)
 
@@ -482,12 +478,9 @@ val open_temp_file :
     file.
 
     [?temp_dir] can be used to choose the directory in which the file is
-    created. For the current directory, use
-    {{: https://ocaml.org/api/Filename.html#VALcurrent_dir_name}
-    [Filename.current_dir_name]}. If not specified, the directory is taken from
-    {{: https://ocaml.org/api/Filename.html#VALget_temp_dir_name}
-    [Filename.get_temp_dir_name]}, which is typically set to your system
-    temporary file directory.
+    created. For the current directory, use {!Stdlib.Filename.current_dir_name}.
+    If not specified, the directory is taken from {!Stdlib.Filename.get_temp_dir_name},
+    which is typically set to your system temporary file directory.
 
     [?prefix] helps determine the name of the file. It will be the prefix
     concatenated with a random sequence of characters. If not specified,
@@ -739,7 +732,7 @@ type byte_order = Lwt_sys.byte_order = Little_endian | Big_endian
     (** Type of byte order *)
 
 val system_byte_order : byte_order
-  (** Same as {!Lwt_sys.byte_order}. *)
+  (** Same as {!val:Lwt_sys.byte_order}. *)
 
 (** {2 Low-level access to the internal buffer} *)
 
@@ -768,7 +761,7 @@ type direct_access = {
 }
 
 val direct_access : 'a channel -> (direct_access -> 'b Lwt.t) -> 'b Lwt.t
-  (** [direct_access ch f] passes to [f] a {!direct_access}
+  (** [direct_access ch f] passes to [f] a {!type:direct_access}
       structure. [f] must use it and update [da_ptr] to reflect how
       many bytes have been read/written. *)
 
@@ -782,7 +775,7 @@ val set_default_buffer_size : int -> unit
   (** Change the default buffer size.
 
       @raise Invalid_argument if the given size is smaller than [16]
-      or greater than [Sys.max_string_length] *)
+      or greater than {!Stdlib.Sys.max_string_length} *)
 
 (** {2 Deprecated} *)
 

src/unix/lwt_main.mli

@@ -63,8 +63,8 @@ val abandon_yielded_and_paused : unit -> unit
     [yield] is now deprecated in favor of the more general {!Lwt.pause}.
     Once [yield] is phased out, this function will be deprecated as well.
 
-    This is meant for use with {!Lwt.fork}, as a way to "abandon" more promise
-    chains that are pending in your process. *)
+    This is meant for use with {!Lwt_unix.fork}, as a way to “abandon” more
+    promise chains that are pending in your process. *)
 
 
 

src/unix/lwt_process.ml

@@ -21,7 +21,7 @@ type redirection =
   | `FD_move of Unix.file_descr ]
 
 (* +-----------------------------------------------------------------+
-   | OS-depentent command spawning                                   |
+   | OS-dependent command spawning                                   |
    +-----------------------------------------------------------------+ *)
 
 type proc = {