Doc: some enhancements in the Algo API doc

lib/algo/algo.mli

-(* Time-stamp: <modified the 02/09/2020 (at 10:27) by Erwan Jahier> *)
-(** {1 The Algorithm programming Interface.} *)
-(** 
-    {1 What's need to be provided by users.}
+(* Time-stamp: <modified the 16/09/2020 (at 15:42) by Erwan Jahier> *)
+(** {1 The Algorithm programming Interface} 
+
     A SASA process is an instance of an algorithm defined via this
     module.   
+*)
+(** 
+    {2 To be provided by users}
 
     In order to define a SASA algorithm, one need to provide an enable
     and a step function:
@@ -18,15 +20,22 @@ type 's neighbor
 type action  = string 
 type 's enable_fun = 's -> 's neighbor list -> action list
 type 's step_fun   = 's -> 's neighbor list -> action -> 's
-(** The first argument  holds the current state of the  process.  As it is
+(** [enable_fun] and [step_fun] have the same arguments in input:
+
+    - The first argument  holds the current state of the  process.  As it is
     polymorphic (['s]),  algorithms designers  can put anything  they need
     into this state (an integer,  a structure, etc.).  The only constraint
     is that all algorithms should use the same type.
     
-    The  second  argument  holds  the  process  neighbors. Note that  SASA
+    - The  second  argument  holds  the  process  neighbors. Note that  SASA
     processes,  that  live  in  graph  nodes, can  only  access  to  their
     immediate  neighbors.  From  each neighbor,  a process  can access  to
-    various information thanks to the functions below.
+    various information (cf [state], [reply], and [weight] functions below).
+
+    [enable_fun] returns the list of enable actions.
+
+    [step_fun], which also takes an action in input, returns the new value 
+    of the local state resulting from the execution of the action.
 *)
 
 type 's state_init_fun = int -> string -> 's
@@ -35,14 +44,47 @@ type 's state_init_fun = int -> string -> 's
    of  node neighbors,  and  the pid.   Anonymous  algorithms are  not
    supposed to use the pid.  *)
 
-(** Returns the processes local state *) 
+(** {2 To be provided optionally} *)
+
+(** {3 Potential function} 
+
+    Let the user define what the potential of a configuration is.
+    Used to explore best/worst case daemons (--worst-daemon)
+*)
+  
+type pid = string
+type 's potential_fun = pid list -> (pid -> 's * 's neighbor list) -> float
+
+
+(** {3 Legitimate Configurations} *)
+  
+type 's legitimate_fun = pid list -> (pid -> 's * 's neighbor list) -> bool
+(** By  default, legitimate  configurations (i.e., global  states) are
+   silent ones.  But  this is not true for  all algorithms.  Predicates
+   of this type are used to redefine what's a legitimate configuration
+   is. *)
+
+
+(** {3 Fault Injection } *)
+  
+type 's fault_fun = int -> string -> 's -> 's
+(** The  fault function is called  on each node to  update their state
+   each  time  a legitimate  configuration  is  reached.  It  takes  3
+   arguments: the number of node neighbors,  the pid, and the value of
+   the current state.  *)
+
+(** {2 Can be used in algorithms} *)
+
+(** {3 Process (local) Information} *)
+  
+(** Returns the neighbor processes local state *) 
 val state : 's neighbor -> 's
 
-(** Returns the  channel number, that let this neighbor  access to the
-   content of the current process, if its neighbor can access it.  The
-   channel number is  the rank,starting at 0, in  the neighbors' list.
-   Returns -1 if the neighbor can not access to the process, which may
-   happen in directed graphs.
+(** Returns the neighbor channel number, that let this neighbor access
+   to the content  of the current process, if its  neighbor can access
+   it.   The  channel  number  is  the  rank,starting  at  0,  in  the
+   neighbors' list.  Returns -1 if the  neighbor can not access to the
+   process, which may happen in directed graphs.
 
    An  algorithm  that  uses  reply,   and  not  the  pid,  is  called
    semi-anonymous. It is called anonymous if it can access none. *)
@@ -53,10 +95,11 @@ val reply : 's neighbor -> int
    returned if not weight is set in the graph. *)
 val weight : 's neighbor -> int
 
+(** For debugging *)
 val print_neighbor: 's neighbor -> unit
 val fmt_print_neighbor: Format.formatter -> 's neighbor -> unit
 
-(** {1 Access to Topological Information}
+(** {3 Topological Information}
 
    When  writing  algorithms, one  can  also  have access  to  topological
    information (i.e., information that are relative to the graph) *)
@@ -79,29 +122,8 @@ val diameter : unit -> int
 val get_graph_attribute : string -> string
 
 
-(** {1 Potential function } 
-
-    Let the user define what the potential of a configuration is.
-    Used to explore best/worst case daemons (--worst-daemon)
-*)
-type pid = string
-type 's potential_fun = pid list -> (pid -> 's * 's neighbor list) -> float
-                      
-(** {1 Legitimate Configurations}  *)
-type 's legitimate_fun = pid list -> (pid -> 's * 's neighbor list) -> bool
-(** By  default, legitimate  configurations (i.e., global  states) are
-   silent ones.  But  this is not true for  all algorithms.  Predicates
-   of this type are used to redefine what's a legitimate configuration
-   is. *)
-                      
-(** {1 Fault Injection}  *)
-type 's fault_fun = int -> string -> 's -> 's
-(** The  fault function is called  on each node to  update their state
-   each  time  a legitimate  configuration  is  reached.  It  takes  3
-   arguments: the number of node neighbors,  the pid, and the value of
-   the current state.  *)
                       
-(** {1 Code Registration}
+(** {2 Code Registration}
 
 The [register: 's to_register -> unit] function must be called once in
    the user code.  *)
@@ -135,7 +157,7 @@ type 's to_register = {
 (** To be called once *)
 val register : 's to_register -> unit
   
-(** {1 Automatic Generation of Registration Code}
+(** {1 Automatic Code Registration }
 
    Once enable and step functions are defined, they need to be
    registered by calling the register function.