Allow documentation for positional args (#4)

CHANGES.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Allow documentation for positional args (#4)
 - Improve filename completion (#3)
 - Stop printing spec errors (#2, fixes #1)
 

examples/fake_git.ml

@@ -27,9 +27,9 @@ let checkout =
 
 let commit =
   let open Arg_parser in
-  let+ _amend = flag [ "amend"; "a" ]
+  let+ _amend = flag [ "amend"; "a" ] ~desc:"Ammend a commit"
   and+ _branch = named_opt [ "b"; "branch" ] branch_conv
-  and+ _message = named_opt [ "m"; "message" ] string
+  and+ _message = named_opt [ "m"; "message" ] string ~desc:"The commit message"
   and+ _files = pos_all file in
   ()
 ;;
@@ -55,10 +55,10 @@ let () =
   let open Command in
   group
     ~desc:"Fake version control"
-    [ subcommand "config" (singleton Arg_parser.unit)
-    ; subcommand "checkout" (singleton checkout)
-    ; subcommand "commit" (singleton commit)
-    ; subcommand "log" (singleton log)
+    [ subcommand "config" (singleton Arg_parser.unit ~desc:"Configure the tool.")
+    ; subcommand "checkout" (singleton checkout ~desc:"Check out a revision.")
+    ; subcommand "commit" (singleton commit ~desc:"Commit your changes.")
+    ; subcommand "log" (singleton log ~desc:"List recent commits.")
     ; subcommand
         "bisect"
         (group

examples/sum.ml

@@ -3,7 +3,7 @@ open Climate
 
 let main =
   let open Arg_parser in
-  let+ args = pos_all int in
+  let+ args = pos_all int ~desc:"The ints to be summed" in
   print_endline (Printf.sprintf "%d" (List.fold_left args ~init:0 ~f:( + )))
 ;;
 

examples/sum2.ml

@@ -2,8 +2,8 @@ open Climate
 
 let main =
   let open Arg_parser in
-  let+ a = pos_req 0 int
-  and+ b = pos_req 1 int in
+  let+ a = pos_req 0 int ~value_name:"LHS" ~desc:"The left hand side of the operation"
+  and+ b = pos_req 1 int ~value_name:"RHS" ~desc:"The right hand side of the operation" in
   print_endline (Printf.sprintf "%d" (a + b))
 ;;
 

src/climate/climate.ml

@@ -453,7 +453,7 @@ module Arg_parser = struct
 
   let flag = flag_gen ~allow_many:false
 
-  let pos_single_gen i conv ~value_name ~required ~completion =
+  let pos_single_gen i conv ~desc ~value_name ~required ~completion =
     let i =
       match Nonnegative_int.of_int i with
       | Some _ -> i
@@ -465,7 +465,8 @@ module Arg_parser = struct
              i
              ~value_name:(Option.value value_name ~default:conv.default_value_name)
              ~required
-             ~completion:(conv_untyped_completion_opt_with_default conv completion))
+             ~completion:(conv_untyped_completion_opt_with_default conv completion)
+             ~desc)
     ; arg_compute =
         (fun context ->
           Raw_arg_table.get_pos context.raw_arg_table i
@@ -478,32 +479,33 @@ module Arg_parser = struct
     }
   ;;
 
-  let pos_opt ?value_name ?completion i conv =
-    pos_single_gen i conv ~value_name ~required:false ~completion
+  let pos_opt ?desc ?value_name ?completion i conv =
+    pos_single_gen i conv ~desc ~value_name ~required:false ~completion
   ;;
 
-  let pos_with_default ?value_name ?completion i conv ~default =
-    pos_opt ?value_name ?completion i conv
+  let pos_with_default ?desc ?value_name ?completion i conv ~default =
+    pos_opt ?desc ?value_name ?completion i conv
     |> map ~f:(function
       | Some x -> x
       | None -> default)
   ;;
 
-  let pos_req ?value_name ?completion i conv =
-    pos_single_gen i conv ~value_name ~required:true ~completion
+  let pos_req ?desc ?value_name ?completion i conv =
+    pos_single_gen i conv ~desc ~value_name ~required:true ~completion
     |> map ~f:(function
       | Some x -> x
       | None -> raise Parse_error.(E (Pos_req_missing i)))
   ;;
 
-  let pos_left_gen i conv ~value_name ~required ~completion =
+  let pos_left_gen i conv ~desc ~value_name ~required ~completion =
     { arg_spec =
         Spec.create_positional
           (Spec.Positional.all_below_exclusive
              i
              ~value_name:(Option.value value_name ~default:conv.default_value_name)
              ~required
-             ~completion:(conv_untyped_completion_opt_with_default conv completion))
+             ~completion:(conv_untyped_completion_opt_with_default conv completion)
+             ~desc)
     ; arg_compute =
         (fun context ->
           let left, _ =
@@ -518,17 +520,18 @@ module Arg_parser = struct
     }
   ;;
 
-  let pos_left ?value_name ?completion i conv =
-    pos_left_gen i conv ~value_name ~required:false ~completion
+  let pos_left ?desc ?value_name ?completion i conv =
+    pos_left_gen i conv ~desc ~value_name ~required:false ~completion
   ;;
 
-  let pos_right_inclusive ?value_name ?completion i_inclusive conv =
+  let pos_right_inclusive ?desc ?value_name ?completion i_inclusive conv =
     { arg_spec =
         Spec.create_positional
           (Spec.Positional.all_above_inclusive
              i_inclusive
              ~value_name:(Option.value value_name ~default:conv.default_value_name)
-             ~completion:(conv_untyped_completion_opt_with_default conv completion))
+             ~completion:(conv_untyped_completion_opt_with_default conv completion)
+             ~desc)
     ; arg_compute =
         (fun context ->
           let _, right =
@@ -543,12 +546,12 @@ module Arg_parser = struct
     }
   ;;
 
-  let pos_right ?value_name ?completion i_exclusive conv =
-    pos_right_inclusive ?value_name ?completion (i_exclusive + 1) conv
+  let pos_right ?desc ?value_name ?completion i_exclusive conv =
+    pos_right_inclusive ?desc ?value_name ?completion (i_exclusive + 1) conv
   ;;
 
-  let pos_all ?value_name ?completion conv =
-    pos_right_inclusive ?value_name ?completion 0 conv
+  let pos_all ?desc ?value_name ?completion conv =
+    pos_right_inclusive ?desc ?value_name ?completion 0 conv
   ;;
 
   let validate t = Spec.validate t.arg_spec
@@ -580,6 +583,8 @@ module Arg_parser = struct
       Format.fprintf ppf "%s" description;
       Format.pp_print_newline ppf ();
       Format.pp_print_newline ppf ());
+    if not (Spec.Positional.is_empty arg_spec.positional)
+    then Spec.positional_help ppf arg_spec;
     if not (Spec.Named.is_empty arg_spec.named) then Spec.named_help ppf arg_spec;
     if not (List.is_empty child_subcommands)
     then (

src/climate/climate.mli

@@ -174,7 +174,8 @@ module Arg_parser : sig
   (** [pos_opt i conv] declares an optional anonymous positional
       argument at position [i] (starting at 0). *)
   val pos_opt
-    :  ?value_name:string
+    :  ?desc:string
+    -> ?value_name:string
     -> ?completion:'a Completion.t
     -> int
     -> 'a conv
@@ -183,7 +184,8 @@ module Arg_parser : sig
   (** [pos_with_default i conv] declares an optional anonymous positional
       argument with a default value at position [i] (starting at 0). *)
   val pos_with_default
-    :  ?value_name:string
+    :  ?desc:string
+    -> ?value_name:string
     -> ?completion:'a Completion.t
     -> int
     -> 'a conv
@@ -193,19 +195,26 @@ module Arg_parser : sig
   (** [pos_req i conv] declares a required anonymous positional
       argument at position [i] (starting at 0). *)
   val pos_req
-    :  ?value_name:string
+    :  ?desc:string
+    -> ?value_name:string
     -> ?completion:'a Completion.t
     -> int
     -> 'a conv
     -> 'a t
 
   (** Parses all positional arguments. *)
-  val pos_all : ?value_name:string -> ?completion:'a Completion.t -> 'a conv -> 'a list t
+  val pos_all
+    :  ?desc:string
+    -> ?value_name:string
+    -> ?completion:'a Completion.t
+    -> 'a conv
+    -> 'a list t
 
   (** [pos_left i conv] parses all positional arguments at positions less than
       i. *)
   val pos_left
-    :  ?value_name:string
+    :  ?desc:string
+    -> ?value_name:string
     -> ?completion:'a Completion.t
     -> int
     -> 'a conv
@@ -214,7 +223,8 @@ module Arg_parser : sig
   (** [pos_right i conv] parses all positional arguments at positions greater
       than i. *)
   val pos_right
-    :  ?value_name:string
+    :  ?desc:string
+    -> ?value_name:string
     -> ?completion:'a Completion.t
     -> int
     -> 'a conv