Shell: minor doc improvement in RPC.

src/node/net/p2p.ml

@@ -454,7 +454,7 @@ module RPC = struct
 
     type info = {
       trusted : bool ;
-      greylisted_end : Time.t ;
+      greylisted_until : Time.t ;
       state : state ;
       peer_id : Peer_id.t option ;
       last_failed_connection : Time.t option ;
@@ -468,21 +468,21 @@ module RPC = struct
     let info_encoding =
       let open Data_encoding in
       conv
-        (fun { trusted ; greylisted_end ; state ; peer_id ;
+        (fun { trusted ; greylisted_until ; state ; peer_id ;
                last_failed_connection ; last_rejected_connection ;
                last_established_connection ; last_disconnection ;
                last_seen ; last_miss ;
              } ->
-          (trusted, greylisted_end, state, peer_id,
+          (trusted, greylisted_until, state, peer_id,
            last_failed_connection, last_rejected_connection,
            last_established_connection, last_disconnection,
            last_seen, last_miss)
         )
-        (fun (trusted, greylisted_end, state, peer_id,
+        (fun (trusted, greylisted_until, state, peer_id,
               last_failed_connection, last_rejected_connection,
               last_established_connection, last_disconnection,
               last_seen, last_miss) ->
-          { trusted ; greylisted_end ; state ; peer_id ;
+          { trusted ; greylisted_until ; state ; peer_id ;
             last_failed_connection ; last_rejected_connection ;
             last_established_connection ; last_disconnection ;
             last_seen ; last_miss ;
@@ -490,7 +490,7 @@ module RPC = struct
         )
         (obj10
            (req "trusted" bool)
-           (dft "greylisted_end" Time.encoding Time.epoch)
+           (dft "greylisted_until" Time.encoding Time.epoch)
            (req "state" state_encoding)
            (opt "peer_id" Peer_id.encoding)
            (opt "last_failed_connection" Time.encoding)
@@ -511,7 +511,7 @@ module RPC = struct
       Point_info.{
         trusted = trusted i ;
         state ; peer_id ;
-        greylisted_end = greylisted_end i ;
+        greylisted_until = greylisted_until i ;
         last_failed_connection = last_failed_connection i ;
         last_rejected_connection = last_rejected_connection i ;
         last_established_connection = last_established_connection i ;
@@ -621,7 +621,7 @@ module RPC = struct
               (req "score" float)
               (req "trusted" bool)
               (req "state" state_encoding)
-              (opt "id_point" Id_point.encoding)
+              (opt "reachable_at" Id_point.encoding)
               (req "stat" Stat.encoding))
            (obj6
               (opt "last_failed_connection" (tup2 Id_point.encoding Time.encoding))

src/node/net/p2p.mli

@@ -217,7 +217,7 @@ module RPC : sig
 
     type info = {
       trusted : bool ;
-      greylisted_end : Time.t ;
+      greylisted_until : Time.t ;
       state : state ;
       peer_id : Peer_id.t option ;
       last_failed_connection : Time.t option ;

src/node/net/p2p_connection_pool.mli

@@ -201,9 +201,9 @@ module LogEvent : sig
     (** The connection was closed for external reason. *)
 
     | Gc_points
-    (** Garbage correction of known point table has been triggered. *)
+    (** Garbage collection of known point table has been triggered. *)
     | Gc_peer_ids
-    (** Garbage correction of known peer_ids table has been triggered. *)
+    (** Garbage collection of known peer_ids table has been triggered. *)
 
   val encoding : t Data_encoding.t
 end

src/node/net/p2p_connection_pool_types.ml

@@ -35,7 +35,7 @@ module Point_info = struct
       let branch_encoding name obj =
         conv (fun x -> (), x) (fun ((), x) -> x)
           (merge_objs
-             (obj1 (req "event" (constant name))) obj) in
+             (obj1 (req "event_kind" (constant name))) obj) in
       union ~tag_size:`Uint8 [
         case ~tag:0 (branch_encoding "outgoing_request" empty)
           (function Outgoing_request -> Some () | _ -> None)
@@ -140,7 +140,7 @@ module Point_info = struct
   let last_rejected_connection s = s.last_rejected_connection
   let greylisted ?(now = Time.now ()) s =
     Time.compare now s.greylisting_end <= 0
-  let greylisted_end s = s.greylisting_end
+  let greylisted_until s = s.greylisting_end
 
   let recent a1 a2 =
     match a1, a2 with

src/node/net/p2p_connection_pool_types.mli

@@ -68,7 +68,7 @@ module Point_info : sig
   val greylisted :
     ?now:Time.t -> 'conn point_info -> bool
 
-  val greylisted_end : 'conn point_info -> Time.t
+  val greylisted_until : 'conn point_info -> Time.t
 
   val point : 'conn point_info -> Point.t
 

src/node/shell/node_rpc_services.ml

@@ -485,7 +485,9 @@ module Protocols = struct
 end
 
 module Network = struct
+
   open P2p_types
+
   let (peer_id_arg : P2p_types.Peer_id.t RPC.Arg.arg) =
     RPC.Arg.make
       ~name:"peer_id"
@@ -528,8 +530,10 @@ module Network = struct
   let monitor_encoding = obj1 (dft "monitor" bool false)
 
   module Connection = struct
+
     let list =
       RPC.service
+        ~description:"List the running P2P connection."
         ~input: empty
         ~output: (list P2p.Connection_info.encoding)
         RPC.Path.(root / "network" / "connection")
@@ -538,58 +542,73 @@ module Network = struct
       RPC.service
         ~input: empty
         ~output: (option P2p.Connection_info.encoding)
+        ~description:"Details about the current P2P connection to the given peer."
         RPC.Path.(root / "network" / "connection" /: peer_id_arg)
 
     let kick =
       RPC.service
         ~input: (obj1 (req "wait" bool))
         ~output: empty
+        ~description:"Forced close of the current P2P connection to the given peer."
         RPC.Path.(root / "network" / "connection" /: peer_id_arg / "kick")
+
   end
 
   module Point = struct
+
     let infos =
       let filter =
         obj1 (dft "filter" (list P2p.RPC.Point.state_encoding) []) in
       RPC.service
         ~input: filter
         ~output: (list (tup2 P2p.Point.encoding P2p.RPC.Point.info_encoding))
+        ~description:"List the pool of known `IP:port` \
+                      used for establishing P2P connections ."
         RPC.Path.(root / "network" / "point")
 
     let info =
       RPC.service
         ~input: empty
         ~output: (option P2p.RPC.Point.info_encoding)
+        ~description: "Details about a given `IP:addr`."
         RPC.Path.(root / "network" / "point" /: point_arg)
 
     let events =
       RPC.service
         ~input: monitor_encoding
         ~output: (list P2p.RPC.Point.Event.encoding)
+        ~description: "Monitor network events related to an `IP:addr`."
         RPC.Path.(root / "network" / "point" /: point_arg / "log")
+
   end
 
   module Peer_id = struct
+
     let infos =
       let filter =
         obj1 (dft "filter" (list P2p.RPC.Peer_id.state_encoding) []) in
       RPC.service
         ~input: filter
         ~output: (list (tup2 P2p.Peer_id.encoding P2p.RPC.Peer_id.info_encoding))
+        ~description:"List the peers the node ever met."
         RPC.Path.(root / "network" / "peer_id")
 
     let info =
       RPC.service
         ~input: empty
         ~output: (option P2p.RPC.Peer_id.info_encoding)
+        ~description:"Details about a given peer."
         RPC.Path.(root / "network" / "peer_id" /: peer_id_arg)
 
     let events =
       RPC.service
         ~input: monitor_encoding
         ~output: (list P2p.RPC.Peer_id.Event.encoding)
+        ~description:"Monitor network events related to a given peer."
         RPC.Path.(root / "network" / "peer_id" /: peer_id_arg / "log")
+
   end
+
 end
 
 let forge_block =