Added clarifying comments

Signed-off-by: Ambre Austen Suhamy <[email protected]>

Author: ElectreAAS

bin/promotion.ml

@@ -68,7 +68,7 @@ module Apply = struct
         ~config
         lock_held_by
         (Rpc_common.fire_request
-           ~name:"promote_but_better"
+           ~name:"promote_but_different"
            ~wait:true
            Dune_rpc_impl.Decl.promote)
         files_to_promote

bin/rpc/rpc_common.mli

@@ -21,9 +21,7 @@ val client_term : Common.Builder.t -> (unit -> 'a Fiber.t) -> 'a
 (** Cmdliner argument for a wait flag. *)
 val wait_term : bool Cmdliner.Term.t
 
-val establish_client_session : wait:bool -> Dune_rpc_client.Client.Connection.t Fiber.t
-
-(** Send a request to the RPC server.
+(** Send a request to the RPC server. If [wait], it will poll forever until a server is listening.
     Should be scheduled by a scheduler that does not come with a RPC server on its own. *)
 val fire_request
   :  name:string

src/dune_rpc_impl/decl.ml

@@ -93,11 +93,19 @@ module Build = struct
 end
 
 module Promote = struct
+  let on_missing fn =
+    User_warning.emit
+      [ Pp.paragraphf
+          "Nothing to promote for %s."
+          (Stdune.Path.Source.to_string_maybe_quoted fn)
+      ]
+  ;;
+
   let sexp =
     let open Conv in
     let to_ = function
       | [] -> Promote.Diff_promotion.All
-      | paths -> These (List.map ~f:Stdune.Path.Source.of_string paths, ignore)
+      | paths -> These (List.map ~f:Stdune.Path.Source.of_string paths, on_missing)
     in
     let from = function
       | Promote.Diff_promotion.All -> []
@@ -113,7 +121,9 @@ module Promote = struct
       ~version:1
   ;;
 
-  let decl = Decl.Request.make ~method_:"promote_but_better" ~generations:[ v1 ]
+  (* Due to conflict with `Dune_rpc_private.Procedures.Public.promote`,
+     this has to be named something other than "promote". *)
+  let decl = Decl.Request.make ~method_:"promote_but_different" ~generations:[ v1 ]
 end
 
 let build = Build.decl

src/dune_rpc_impl/server.ml

@@ -396,6 +396,8 @@ let handler (t : _ t Fdecl.t) handle : 'build_arg Dune_rpc_server.Handler.t =
     in
     Handler.implement_request rpc Decl.promote f
   in
+  (* The two handlers above and below implement the same thing: 'promote',
+     but in two slightly different ways. Maybe one should be removed/deprecated? *)
   let () =
     let f _ path =
       let files = For_handlers.source_path_of_string path in