chore: force cmdliner doc argument to be explicit (#12728)

Signed-off-by: Ali Caglayan <[email protected]>

Author: Alizter

bin/arg.ml

@@ -1,6 +1,10 @@
 open Stdune
 include Cmdliner.Arg
 
+let info ?deprecated ?absent ?docs ?docv ~doc ?env names =
+  Cmdliner.Arg.info ?deprecated ?absent ?docs ?docv ?doc ?env names
+;;
+
 include struct
   open Dune_lang
   module Stanza = Stanza

bin/arg.mli

@@ -1,8 +1,19 @@
 open Stdune
 
 include module type of struct
-  include Cmdliner.Arg
-end
+    include Cmdliner.Arg
+  end
+  with type info := Cmdliner.Arg.info
+
+val info
+  :  ?deprecated:string
+  -> ?absent:string
+  -> ?docs:string
+  -> ?docv:string
+  -> doc:string option
+  -> ?env:Cmdliner.Cmd.Env.info
+  -> string list
+  -> Cmdliner.Arg.info
 
 module Path : sig
   module External : sig

bin/build.ml

@@ -162,7 +162,8 @@ let build =
         ]
     ]
   in
-  let name_ = Arg.info [] ~docv:"TARGET" in
+  (* CR-someday Alizter: document this option *)
+  let name_ = Arg.info [] ~docv:"TARGET" ~doc:None in
   let term =
     let+ builder = Common.Builder.term
     and+ targets = Arg.(value & pos_all dep [] name_)
@@ -174,10 +175,11 @@ let build =
             [ "alias-rec" ]
             ~docv:"ALIAS"
             ~doc:
-              "Build the alias $(docv) in its parent directory and all subdirectories. \
-               Equivalent to the build target $(b,@)$(docv). Example: $(b,--alias-rec \
-               dir/foo) builds the $(b,foo) alias in $(b,dir/) and all its \
-               subdirectories. Repeatable.")
+              (Some
+                 "Build the alias $(docv) in its parent directory and all \
+                  subdirectories. Equivalent to the build target $(b,@)$(docv). Example: \
+                  $(b,--alias-rec dir/foo) builds the $(b,foo) alias in $(b,dir/) and \
+                  all its subdirectories. Repeatable."))
     and+ aliases =
       Arg.(
         value
@@ -186,9 +188,10 @@ let build =
             [ "alias" ]
             ~docv:"ALIAS"
             ~doc:
-              "Build $(docv) in its parent directory only. Equivalent to the build \
-               target $(b,@@)$(docv). Example: $(b,--alias dir/foo) builds the $(b,foo) \
-               alias in $(b,dir/) only. Repeatable.")
+              (Some
+                 "Build $(docv) in its parent directory only. Equivalent to the build \
+                  target $(b,@@)$(docv). Example: $(b,--alias dir/foo) builds the \
+                  $(b,foo) alias in $(b,dir/) only. Repeatable."))
     in
     let targets = List.concat [ targets; aliases; aliases_rec ] in
     let targets =

bin/cache.ml

@@ -28,7 +28,7 @@ let trim =
          & info
              ~docv:"BYTES"
              [ "trimmed-size" ]
-             ~doc:"Size to trim from the cache. $(docv) is the same as for --size.")
+             ~doc:(Some "Size to trim from the cache. $(docv) is the same as for --size."))
      and+ size =
        Arg.(
          value
@@ -37,13 +37,14 @@ let trim =
              ~docv:"BYTES"
              [ "size" ]
              ~doc:
-               (sprintf
-                  "Size to trim the cache to. $(docv) is the number of bytes followed by \
-                   a unit. Byte units can be one of %s."
-                  (String.enumerate_or
-                     (List.map
-                        ~f:(fun (units, _) -> List.hd units)
-                        Bytes_unit.conversion_table))))
+               (Some
+                  (sprintf
+                     "Size to trim the cache to. $(docv) is the number of bytes followed \
+                      by a unit. Byte units can be one of %s."
+                     (String.enumerate_or
+                        (List.map
+                           ~f:(fun (units, _) -> List.hd units)
+                           Bytes_unit.conversion_table)))))
      in
      Log.init_disabled ();
      let open Result.O in
@@ -84,7 +85,9 @@ let size =
        Arg.(
          value
          & flag
-         & info [ "machine-readable" ] ~doc:"Outputs size as a plain number of bytes.")
+         & info
+             [ "machine-readable" ]
+             ~doc:(Some "Outputs size as a plain number of bytes."))
      in
      let size = Dune_cache.Trimmer.overhead_size () in
      if machine_readable