Improve CLI doc and error message

CHANGES.md

@@ -4,6 +4,9 @@
 
 ### Changed
 
+- Improve CLI doc and error message for opam fields (#417, @Firobe, reported by
+    @reynir in #416)
+
 ### Deprecated
 
 ### Fixed

lib/serial_shape.ml

@@ -201,7 +201,10 @@ let parse_list s =
     match (s.[0], s.[len - 1]) with
     | '[', ']' -> split_list (String.sub s ~pos:1 ~len:(len - 2))
     | ('[' as delim), _ -> unmatched_list_delimiter ~delim
-    | _ -> Rresult.R.error_msg "list or pairs must be delimited by '[' and ']'"
+    | _ ->
+        Rresult.R.error_msg
+          "a list is expected. Lists must be of the form '[x,y,z]' (i.e. \
+           delimited by '[' and ']')"
 
 let rec cmdliner_parse : type a. a t -> string -> (a, Rresult.R.msg) result =
  fun shape value ->

lib/source_opam_config.ml

@@ -6,6 +6,7 @@ module type FIELD_SHAPE = sig
   val name : string
   val shape : t Serial_shape.t
   val merge : t list -> (t, Rresult.R.msg) result
+  val example : string
 end
 
 module type FIELD = sig
@@ -52,8 +53,9 @@ module Make_field (X : FIELD_SHAPE) : FIELD with type t = X.t = struct
     let doc =
       Printf.sprintf
         "CLI equivalent of the %s opam field. Use this to complement the \
-         corresponding fields in your local opam files."
-        (Opam.Extra_field.name field)
+         corresponding fields in your local opam files.
+         Example value: %s"
+        (Opam.Extra_field.name field) X.example
     in
     Cmdliner.Arg.(opt (some cmdliner_conv) None (info ~doc ~docv [ long_name ]))
 
@@ -63,8 +65,9 @@ module Make_field (X : FIELD_SHAPE) : FIELD with type t = X.t = struct
     let doc =
       Printf.sprintf
         "CLI equivalent of the %s opam field. Use this to replace the \
-         corresponding fields in your local opam files."
-        (Opam.Extra_field.name field)
+         corresponding fields in your local opam files.
+         Example value: %s"
+        (Opam.Extra_field.name field) X.example
     in
     Cmdliner.Arg.(opt (some cmdliner_conv) None (info ~doc ~docv [ long_name ]))
 end
@@ -74,6 +77,9 @@ module Opam_repositories_shape = struct
 
   let name = "opam-repositories"
 
+  let example =
+      "'[git+https://me.com/my-repo,git+https://me.com/my-repo-2]'"
+
   let from_repr l =
     let urls = List.map ~f:OpamUrl.of_string l in
     Ok (OpamUrl.Set.of_list urls)
@@ -96,6 +102,8 @@ module Opam_global_vars_shape = struct
 
   let name = "global-opam-vars"
 
+  let example = "'[[arch,x86_64],[os-family,debian]]'"
+
   let var_content_from_repr choice =
     match choice with
     | `C1 b -> Ok (OpamVariable.B b)
@@ -161,6 +169,8 @@ module Opam_provided_shape = struct
 
   let name = "opam-provided"
 
+  let example = "'[ocamlformat,patdiff]'"
+
   let from_repr repr =
     let l = match repr with `C1 l -> l | `C2 s -> [ s ] in
     l

test/lib/test_serial_shape.ml

@@ -137,7 +137,7 @@ let test_cmdliner_parse =
     make_test ~name:"list without delim"
       ~shape:Serial_shape.(list bool)
       ~expected:
-        (Rresult.R.error_msg "list or pairs must be delimited by '[' and ']'")
+        (Rresult.R.error_msg "a list is expected. Lists must be of the form '[x,y,z]' (i.e. delimited by '[' and ']')")
       ~value:"true,false,true";
     make_test ~name:"choice c1"
       ~shape:Serial_shape.(choice3 bool (list bool) string)