Use @deprecated doc tag for all deprecated values

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"]
 

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.

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,14 +1593,17 @@ 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. *)
 
 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. *)