driver.mld: Print the slowest commands

These commands can be reproduced with instrumentation enabled to debug
performance problems.

doc/driver.mld

@@ -727,10 +727,42 @@ html/odoc/odoc_html/Odoc_html/Types
 html/odoc/odoc_html/Odoc_html/Types/index.html
 ]}
 
+Some code to analyze the list of executed commands:
+
+{[
+(** Return the list of executed commands where the first argument was [cmd]. *)
+let filter_commands cmd =
+  List.filter
+    (fun (cmd', _, _) ->
+      match Bos.Cmd.to_list cmd' with
+      | _ :: cmd' :: _ -> cmd = cmd'
+      | _ -> false)
+    !commands
+
+(** Returns the [k] commands that took the most time for a given subcommand. *)
+let k_longest_commands cmd k =
+  filter_commands cmd |>
+  List.sort (fun (_, a, _) (_, b, _) -> Float.compare b a) |>
+  List.filteri (fun i _ -> i < k)
+
+(** Print an executed command and its time. *)
+let print_cmd (cmd, t, _) =
+  Printf.printf "[%4.2f] $ %s\n" t (Cmd.to_string cmd)
+]}
+
 If needed, the list of commands executed so far can be shown by de-commenting this block:
 
 {[
-# (* List.iter (fun (cmd, _) -> Printf.printf "$ %s\n" (Cmd.to_string cmd)) (List.rev !commands);; *)
+# (* List.iter print_cmd (List.rev !commands);; *)
+]}
+
+Print the slowest commands for each subcommands:
+(for the record, these commands are run from directory `_build/default/doc`)
+
+{[
+# (* List.iter print_cmd (k_longest_commands "compile" 5) *)
+# (* List.iter print_cmd (k_longest_commands "link" 5) *)
+# (* List.iter print_cmd (k_longest_commands "html-generate" 5) *)
 ]}
 
 This last block analyze the running times so that they can be submitted to
@@ -740,15 +772,6 @@ This last block analyze the running times so that they can be submitted to
 (* *)
 #require "yojson" ;;
 
-(** Return the list of executed commands where the first argument was [cmd]. *)
-let filter_commands cmd =
-  List.filter
-    (fun (cmd', _, _) ->
-      match Bos.Cmd.to_list cmd' with
-      | _ :: cmd' :: _ -> cmd = cmd'
-      | _ -> false)
-    !commands
-
 (** Analyze the running time of a command. *)
 let compute_metric_cmd cmd =
   let rec compute min_ max_ total count = function