Annotate deprecations

Did not annotate Lwt_sequence for the time being, as it is still used by
the Lwt API.

Closes #107.

src/core/lwt.mli

@@ -315,10 +315,14 @@ type +'a result = ('a, exn) Result.result
       This type is defined as [('a, exn) Result.result] since 2.6.0. *)
 
 val make_value : 'a -> 'a result
+  [@@ocaml.deprecated
+    "Use Result.Ok, which is the same as Ok since OCaml 4.03."]
   (** [value x] creates a result containing the value [x].
       @deprecated Since 2.6.0. Use {!Result.Ok} *)
 
 val make_error : exn -> 'a result
+  [@@ocaml.deprecated
+    "Use Result.Error, which is the same as Error since OCaml 4.03."]
   (** [error e] creates a result containing the exception [e].
       @deprecated Since 2.6.0. Use {!Result.Error} *)
 

src/core/lwt_pqueue.mli

@@ -40,6 +40,10 @@
     {{: http://ocaml-batteries-team.github.io/batteries-included/hdoc2/BatHeap.html}
     Batteries}. *)
 
+[@@@ocaml.deprecated
+"This module is an implementation detail of Lwt. See
+  http://ocsigen.org/lwt/dev/api/Lwt_pqueue"]
+
 (** Signature pairing an element type with an ordering function. *)
 module type OrderedType =
   sig

src/core/lwt_result.mli

@@ -25,6 +25,8 @@
 (** This module provides helpers for values of type [('a, 'b) result Lwt.t].
     The module is experimental and may change in the future. *)
 
+[@@@ocaml.deprecated "This module will be removed in the future."]
+
 type (+'a, +'b) t = ('a, 'b) Result.result Lwt.t
 
 val return : 'a -> ('a, _) t

src/core/lwt_stream.mli

@@ -239,16 +239,18 @@ val closed : 'a t -> unit Lwt.t
       @since 2.6.0 *)
 
 val on_termination : 'a t -> (unit -> unit) -> unit
+  [@@ocaml.deprecated "Bind on Lwt_stream.closed."]
   (** [on_termination st f] executes [f] when the end of the stream [st]
       is reached. Note that the stream may still contain elements if
       {!peek} or similar was used.
 
-      @deprecated Use [closed]. *)
+      @deprecated Use {!closed}. *)
 
 val on_terminate : 'a t -> (unit -> unit) -> unit
-  (** Same as [on_termination].
+  [@@ocaml.deprecated "Bind on Lwt_stream.closed."]
+  (** Same as {!on_termination}.
 
-      @deprecated Use [closed]. *)
+      @deprecated Use {!closed}. *)
 
 (** {2 Stream transversal} *)
 

src/preemptive/lwt_preemptive.ml

@@ -188,17 +188,17 @@ let nbthreadsbusy () = !threads_count - Queue.length workers
    | Detaching                                                       |
    +-----------------------------------------------------------------+ *)
 
-let init_result = Lwt.make_error (Failure "Lwt_preemptive.detach")
+let init_result = Result.Error (Failure "Lwt_preemptive.detach")
 
 let detach f args =
   simple_init ();
   let result = ref init_result in
   (* The task for the worker thread: *)
   let task () =
     try
-      result := Lwt.make_value (f args)
+      result := Result.Ok (f args)
     with exn ->
-      result := Lwt.make_error exn
+      result := Result.Error exn
   in
   get_worker () >>= fun worker ->
   let waiter, wakener = Lwt.wait () in

src/simple_top/lwt_simple_top.ml

@@ -21,7 +21,11 @@
  *)
 
 (* Integration with the toplevel for people who do not use the
-   enhanced toplevel (the utop project). *)
+   enhanced toplevel (the utop project). This module is deprecated. *)
+
+[@@@ocaml.deprecated
+"Use utop. See
+  https://github.com/diml/utop"]
 
 open Lwt.Infix
 

src/unix/lwt_chan.mli

@@ -25,6 +25,8 @@
 
 (** Note: the {!Lwt_io} module deprecates this module. *)
 
+[@@@ocaml.deprecated "Use module Lwt_io."]
+
 (** {3 Cooperative input channels} *)
 type in_channel = Lwt_io.input_channel
 

src/unix/lwt_engine.ml

@@ -226,6 +226,7 @@ module Sleep_queue =
                     type t = sleeper
                     let compare {time = t1; _} {time = t2; _} = compare t1 t2
                   end)
+  [@@ocaml.warning "-3"]
 
 module Fd_map = Map.Make(struct type t = Unix.file_descr let compare = compare end)
 

src/unix/lwt_sys.mli

@@ -52,4 +52,5 @@ val byte_order : byte_order
   (** The byte order used by the computer running the program. *)
 
 val windows : bool
+  [@@ocaml.deprecated "Use Sys.win32."]
   (** @deprecated Use [Sys.win32]. *)

src/unix/lwt_unix.ml

@@ -184,9 +184,9 @@ let wait_for_jobs () =
 
 let wrap_result f x =
   try
-    Lwt.make_value (f x)
+    Result.Ok (f x)
   with exn ->
-    Lwt.make_error exn
+    Result.Error exn
 
 let run_job_aux async_method job result =
   (* Starts the job. *)
@@ -242,9 +242,9 @@ external run_job_sync : 'a job -> 'a = "lwt_unix_run_job_sync"
 
 let self_result job =
   try
-    Lwt.make_value (self_result job)
+    Result.Ok (self_result job)
   with exn ->
-    Lwt.make_error exn
+    Result.Error exn
 
 let run_job ?async_method job =
   let async_method = choose_async_method async_method in
@@ -1258,15 +1258,15 @@ let files_of_directory path =
 
 let pipe () =
   let (out_fd, in_fd) = Unix.pipe() in
-  (mk_ch ~blocking:Lwt_sys.windows out_fd, mk_ch ~blocking:Lwt_sys.windows in_fd)
+  (mk_ch ~blocking:Sys.win32 out_fd, mk_ch ~blocking:Sys.win32 in_fd)
 
 let pipe_in () =
   let (out_fd, in_fd) = Unix.pipe() in
-  (mk_ch ~blocking:Lwt_sys.windows out_fd, in_fd)
+  (mk_ch ~blocking:Sys.win32 out_fd, in_fd)
 
 let pipe_out () =
   let (out_fd, in_fd) = Unix.pipe() in
-  (out_fd, mk_ch ~blocking:Lwt_sys.windows in_fd)
+  (out_fd, mk_ch ~blocking:Sys.win32 in_fd)
 
 let mkfifo name perms =
   if Sys.win32 then

src/unix/lwt_unix.mli

@@ -1286,6 +1286,7 @@ val execute_job :
   job : 'a job ->
   result : ('a job -> 'b) ->
   free : ('a job -> unit) -> 'b Lwt.t
+  [@@ocaml.deprecated "Use Lwt_unix.run_job."]
   (** @deprecated Use [run_job]. *)
 
 (** {2 Notifications} *)
@@ -1357,7 +1358,9 @@ val set_affinity : ?pid : int -> int list -> unit
 (**/**)
 
 val run : 'a Lwt.t -> 'a
+  [@@ocaml.deprecated "Use Lwt_main.run."]
   (** @deprecated Use [Lwt_main.run]. *)
 
 val has_wait4 : bool
+  [@@ocaml.deprecated "Use Lwt_sys.have `wait4."]
   (** @deprecated Use [Lwt_sys.have `wait4]. *)

tests/core/test_lwt_stream.ml

@@ -331,7 +331,8 @@ let suite = suite "lwt_stream" [
     (fun () ->
       let st = Lwt_stream.of_list [1; 2] in
       let b = ref false in
-      Lwt_stream.on_termination st (fun () -> b := true);
+      (Lwt_stream.on_termination [@ocaml.warning "-3"])
+        st (fun () -> b := true);
       ignore (Lwt_stream.peek st);
       let b1 = !b = false in
       ignore (Lwt_stream.junk st);
@@ -349,7 +350,8 @@ let suite = suite "lwt_stream" [
       let b1 = not (Lwt_stream.is_closed st) in
       ignore (Lwt_stream.junk st);
       let b2 = Lwt_stream.is_closed st in
-      Lwt_stream.on_termination st (fun () -> b := true);
+      (Lwt_stream.on_termination [@ocaml.warning "-3"])
+        st (fun () -> b := true);
       Lwt.return (b1 && b2 && !b));
 
   test "choose_exhausted"