From 7c763f19f33c3f5fd54e3e16abf3c3104c683bf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Proust?= Date: Thu, 2 Dec 2021 08:26:46 +0100 Subject: [PATCH] Use @deprecated doc tag for all deprecated values --- src/core/lwt.mli | 17 +++++++++++------ src/unix/lwt_main.mli | 6 +++--- src/unix/lwt_unix.cppo.mli | 13 ++++++++++--- 3 files changed, 24 insertions(+), 12 deletions(-) diff --git a/src/core/lwt.mli b/src/core/lwt.mli index a37fe6003..5c8bc43f8 100644 --- a/src/core/lwt.mli +++ b/src/core/lwt.mli @@ -1795,7 +1795,9 @@ val make_value : 'a -> 'a result {{: https://ocaml.org/api/Stdlib.html#TYPEresult} [Ok v]} since OCaml 4.03. If you need compatibility with OCaml 4.02, use [Result.Ok] and depend on opam package - {{: https://opam.ocaml.org/packages/result/} [result]}. *) + {{: https://opam.ocaml.org/packages/result/} [result]}. + + @deprecated Use [Result.Ok] instead *) val make_error : exn -> _ result [@@ocaml.deprecated @@ -1804,7 +1806,9 @@ val make_error : exn -> _ result {{: https://ocaml.org/api/Stdlib.html#TYPEresult} [Error exn]} since OCaml 4.03. If you need compatibility with OCaml 4.02, use [Result.Error] and depend on opam package - {{: https://opam.ocaml.org/packages/result/} [result]}. *) + {{: https://opam.ocaml.org/packages/result/} [result]}. + + @deprecated Use [Result.Error] instead. *) val waiter_of_wakener : 'a u -> 'a t [@@ocaml.deprecated @@ -1814,8 +1818,7 @@ val waiter_of_wakener : 'a u -> 'a t (** [Lwt.waiter_of_wakener r] evaluates to the promise associated with resolver [r]. - It is recommended to explicitly keep the reference to the promise - instead. *) + @deprecated Keep the reference to the promise instead. *) @@ -1836,7 +1839,7 @@ Lwt.on_cancel p (fun () -> Lwt_sequence.remove node); p ]} - Use of this function is discouraged for two reasons: + @deprecated Use of this function is discouraged for two reasons: - {!Lwt_sequence} should not be used outside Lwt. - This function only exists because it performs a minor internal @@ -1847,7 +1850,9 @@ val add_task_l : ('a u) Lwt_sequence.t -> 'a t " Deprecated because Lwt_sequence is an implementation detail of Lwt. See https://github.com/ocsigen/lwt/issues/361"] (** Like {!Lwt.add_task_r}, but the equivalent code calls {!Lwt_sequence.add_l} - instead. *) + instead. + + @deprecated See [add_task_r]. *) [@@@ocaml.warning "+3"] diff --git a/src/unix/lwt_main.mli b/src/unix/lwt_main.mli index 11c28b901..75a3a6e39 100644 --- a/src/unix/lwt_main.mli +++ b/src/unix/lwt_main.mli @@ -47,9 +47,9 @@ val yield : unit -> unit Lwt.t [@@deprecated "Use Lwt.pause instead"] calling all currently ready callbacks, i.e. it is fulfilled on the next “tick.” - [yield] is now deprecated in favor of the more general {!Lwt.pause} - in order to avoid discrepancies in resolution (see below) and stay - compatible with other execution environments such as js_of_ocaml. + @deprecated Since 5.5.0 [yield] is deprecated in favor of the more general + {!Lwt.pause} in order to avoid discrepancies in resolution (see below) and + stay compatible with other execution environments such as js_of_ocaml. Currently, paused promises are resolved more frequently than yielded promises. The difference is unintended but existing applications could depend on it. diff --git a/src/unix/lwt_unix.cppo.mli b/src/unix/lwt_unix.cppo.mli index c8bdbb96f..758780422 100644 --- a/src/unix/lwt_unix.cppo.mli +++ b/src/unix/lwt_unix.cppo.mli @@ -53,9 +53,13 @@ val sleep : float -> unit Lwt.t val yield : unit -> unit Lwt.t [@@deprecated "Use Lwt.pause instead"] (** [yield ()] is a promise in a pending state. It resumes itself as soon as - possible and resolves with value [()]. *) + possible and resolves with value [()]. + + @deprecated Since 5.5.0 [yield] is deprecated. Use the more general + {!Lwt.pause} instead. See {!Lwt_main.yield} for additional details. *) val auto_yield : float -> (unit -> unit Lwt.t) [@@deprecated "Use Lwt_unix.auto_pause instead"] +(** @deprecated Since 5.5.0. Use {!auto_pause} instead. *) val auto_pause : float -> (unit -> unit Lwt.t) (** [auto_pause timeout] returns a function [f], and [f ()] has the following @@ -1295,8 +1299,8 @@ type async_method = This is the default. *) | Async_switch [@ocaml.deprecated " Use Lwt_unix.Async_detach."] - (** Currently a synonym for [Async_detach]. This was a different method in - the past. *) + (** @deprecated A synonym for [Async_detach]. This was a + different method in the past. *) val default_async_method : unit -> async_method [@@ocaml.deprecated @@ -1589,6 +1593,7 @@ val has_wait4 : bool val somaxconn : unit -> int [@@ocaml.deprecated " This is an internal function."] + (** @deprecated This is for internal use only. *) val retained : 'a -> bool ref (** @deprecated Used for testing. *) @@ -1596,7 +1601,9 @@ val retained : 'a -> bool ref val read_bigarray : string -> file_descr -> IO_vectors._bigarray -> int -> int -> int Lwt.t [@@ocaml.deprecated " This is an internal function."] + (** @deprecated This is for internal use only. *) val write_bigarray : string -> file_descr -> IO_vectors._bigarray -> int -> int -> int Lwt.t [@@ocaml.deprecated " This is an internal function."] + (** @deprecated This is for internal use only. *)