fix(src/main/*): Complete exit codes description in man for each command/subcommand

Author: hernoufM

src/main/learnocaml_client.ml

@@ -729,9 +729,17 @@ module Init = struct
   let man = man "Initialize the configuration file with the server, and \
                  a token or a nickname+secret pair"
 
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Input error: unable to find a server URL or connection token." 1
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
   let info =
     Cmd.info 
       ~man
+      ~exits
       ~sdocs:Manpage.s_options
       ~doc:"Initialize the configuration file."
       "init"
@@ -819,9 +827,19 @@ module Grade = struct
       "Grades an OCaml exercise using a learn-ocaml server, and submits \
         solutions."
 
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Server-side error: either unable to reach the server or request has been failed." 1
+    ; info ~doc:"Input error: unable to find a file to grade or token isn't valid." 2
+    ; info ~doc:"Grading failed." 10
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
   let info =
     Cmd.info 
       ~man
+      ~exits
       ~sdocs:Manpage.s_options
       ~doc:"Learn-ocaml grading client."
       "grade"        
@@ -850,7 +868,14 @@ module Print_token = struct
 
   let man = man explanation
 
-  let info = Cmd.info ~man ~doc:explanation ~sdocs:Manpage.s_options "print-token"
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Server error: could not reach the server or config file wasn't found." 1
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
+  let info = Cmd.info ~man ~exits ~doc:explanation ~sdocs:Manpage.s_options "print-token"
 
   let term = use_global print_tok
 end
@@ -865,8 +890,15 @@ module Print_server = struct
   let explanation = "Just print the configured server."
 
   let man = man explanation
-          
-  let info = Cmd.info ~man ~doc:explanation ~sdocs:Manpage.s_options "print-server"
+  
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Server error: could not reach the server or config file wasn't found." 1
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
+  let info = Cmd.info ~man ~exits ~doc:explanation ~sdocs:Manpage.s_options "print-server"
 
   let term = use_global print_server        
 
@@ -948,7 +980,7 @@ module Server_version = struct
     let open Cmd.Exit in
     [ info ~doc:"Default exit." ok
     ; info ~doc:"Unable to reach the server." 1
-    ; info ~doc:"Input error: unable to find a server URL." 2
+    ; info ~doc:"Input error: unable to find a server URL or config file." 2
     ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
     ]
 
@@ -971,9 +1003,17 @@ module Set_options = struct
       "Overwrite the configuration file with the command-line options \
        ($(b,--server), $(b,--token))."
 
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Server error: config file wasn't found." 1
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
   let info =
     Cmd.info 
       ~man
+      ~exits
       ~sdocs:Manpage.s_options
       ~doc:"Set configuration."
       "set-options"
@@ -1050,9 +1090,11 @@ module Fetch = struct
   let exits =
     let open Cmd.Exit in
     [ info ~doc:"Default exit." ok
-    ; info ~doc:"There was a file already present on the local side." 1
+    ; info ~doc:"Either sever-side error or there was a file already present on the local side." 1
     ; info ~doc:"A specified exercise was not found on the server." 2
-    ; info ~doc:"Both of 1 and 2." 3 ]
+    ; info ~doc:"Both of 1 (for local side) and 2." 3
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
 
   let info =
     Cmd.info 
@@ -1091,9 +1133,18 @@ module Create_token = struct
   let man = man "Create a token on the server with the desired nickname.\
                  Prodiving a token will test if it exists on the server."
 
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Server error: either unable to reach the server or request has been failed." 1
+    ; info ~doc:"Input error: nickname wasn't provided." 2
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
   let info =
     Cmd.info 
       ~man
+      ~exits
       ~sdocs:Manpage.s_options
       ~doc:"Create a token."
       "create-token"
@@ -1125,9 +1176,19 @@ module Template = struct
 
   let man = man "Get the template of a given exercise"
 
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Sever error: unable to find config file or request has been failed." 1
+    ; info ~doc:"Input error: exercise id wasn't provided." 2
+    ; info ~doc:"Exercise with given id already exists." 3
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
   let info =
     Cmd.info 
       ~man
+      ~exits
       ~sdocs:Manpage.s_options
       ~doc:"Get the template of a given exercise."
       "template"
@@ -1161,7 +1222,14 @@ module Exercise_list = struct
 
   let man = man doc
 
-  let info = Cmd.info ~man ~doc:doc ~sdocs:Manpage.s_options "exercise-list"
+  let exits =
+    let open Cmd.Exit in
+    [ info ~doc:"Default exit." ok
+    ; info ~doc:"Sever error: unable to find config file or request has been failed." 1
+    ; info ~doc:"The client's version is incompatible (too old?) w.r.t. the server." 70
+    ]
+
+  let info = Cmd.info ~man ~exits ~doc:doc ~sdocs:Manpage.s_options "exercise-list"
 
   let term = use_global exercise_list
 end
@@ -1194,6 +1262,7 @@ module Main = struct
     Cmd.info
       ~version 
       ~man
+      ~exits:Grade.exits
       ~sdocs:s_options
       ~doc:"Learn-ocaml client CLI."
       "learn-ocaml-client"

src/main/learnocaml_main.ml

@@ -7,6 +7,7 @@
  * included LICENSE file for details. *)
 
 open Lwt.Infix
+open Cmdliner
 
 module StringSet = Set.Make(String)
 
@@ -24,7 +25,6 @@ let readlink f =
   with Sys_error _ -> Sys.chdir (Filename.get_temp_dir_name ()); f
 
 module Args = struct
-  open Cmdliner
   open Arg
 
   type command = Grade | Build | Serve
@@ -428,7 +428,7 @@ let main o =
   exit ret
 
 let man = 
-  let open Cmdliner.Manpage in
+  let open Manpage in
   [
   `S s_description;
   `P "This program performs various tasks related to generating, serving and \
@@ -460,17 +460,25 @@ let man =
       $(i,https://github.com/ocaml-sf/learn-ocaml/issues)";
 ]
 
+let exits =
+  let open Cmd.Exit in
+  [ info ~doc:"Default exit." ok
+  ; info ~doc:"Client-side failure whose cause is printed on stderr. Caused by $(b,grade) or $(b,build) commands." 1
+  ; info ~doc:"Uncaught exception." 2
+  ; info ~doc:"Server error whose cause is printed on stderr. Caused by $(b,serve) command." 10
+  ]
+
 let main_info =
-  Cmdliner.Cmd.info 
-    ~man 
+  Cmd.info 
+    ~man
+    ~exits
     ~doc:"Learn-ocaml web-app manager"
     ~version:Learnocaml_api.version 
     "learn-ocaml"
 
-let main_term = Cmdliner.Term.(const main $ Args.term)
+let main_term = Term.(const main $ Args.term)
 
 let () =
-  let open Cmdliner in
   match
     Cmd.eval_value ~catch:false (Cmd.v main_info main_term)
   with

src/main/learnocaml_server_main.ml

@@ -87,10 +87,21 @@ let base_url =
        Mandatory for '$(b,learn-ocaml build)' if the site is not hosted in path '/', \
        which typically occurs for static deployment."
 
+let  exits =
+  let open Cmd.Exit in
+  [ info ~doc:"Default exit." ok
+  ; info ~doc:"Uncaught exception." 2
+  ; info ~doc:"Server error whose cause is printed on stderr." 10
+  ; info ~doc:"Aborting. Server internal error occured in less then 15 seconds after the launch." 20
+  ; info ~doc:"Termination signal (SIGTERM) recieved by server." 113
+  ; info ~doc:"Interruption signal (SIGINT) recieved by server." 126
+  ]
+
 let main_info =
   Cmd.info
     ~man
     ~doc:"Learn-ocaml native server"
+    ~exits
     ~sdocs:Manpage.s_options
     ~version:Learnocaml_api.version
     "learn-ocaml"