From b2b1c8e30b85fa78282e0b4380dd885dc2c453a4 Mon Sep 17 00:00:00 2001
From: Benjamin Canou <benjamin@canou.fr>
Date: Tue, 5 Jun 2018 16:50:51 +0200
Subject: [PATCH] Shell: fill some placeholder docs

---
 src/lib_base/fitness.ml                    |  9 +++++++--
 src/lib_shell_services/block_services.ml   |  4 ++--
 src/lib_shell_services/monitor_services.ml | 18 ++++++++++++++----
 3 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/src/lib_base/fitness.ml b/src/lib_base/fitness.ml
index 002a9a83f..ffd7b24b9 100644
--- a/src/lib_base/fitness.ml
+++ b/src/lib_base/fitness.ml
@@ -53,8 +53,13 @@ let rec pp fmt = function
 let encoding =
   let open Data_encoding in
   def "fitness"
-    ~title: "Fitness"
-    ~description: "... FIXME ..." @@
+    ~title: "Block fitness"
+    ~description:
+      "The fitness, or score, of a block, that allow the Tezos to \
+       decide which chain is the best. A fitness value is a list of \
+       byte sequences. They are compared as follows: shortest lists \
+       are smaller; lists of the same length are compared according to \
+       the lexicographical order." @@
   splitted
     ~json: (list bytes)
     ~binary:
diff --git a/src/lib_shell_services/block_services.ml b/src/lib_shell_services/block_services.ml
index 0d6f380d1..a56c8ab18 100644
--- a/src/lib_shell_services/block_services.ml
+++ b/src/lib_shell_services/block_services.ml
@@ -392,7 +392,7 @@ module Make(Proto : PROTO)(Next_proto : PROTO) = struct
       let list_arg =
         let name = "list_offset" in
         let descr =
-          "..." in
+          "Index `n` of the requested validation pass." in
         let construct = string_of_int in
         let destruct s =
           try Ok (int_of_string s)
@@ -402,7 +402,7 @@ module Make(Proto : PROTO)(Next_proto : PROTO) = struct
       let offset_arg =
         let name = "operation_offset" in
         let descr =
-          "..." in
+          "Index `m` of the requested operation in its validation pass." in
         let construct = string_of_int in
         let destruct s =
           try Ok (int_of_string s)
diff --git a/src/lib_shell_services/monitor_services.ml b/src/lib_shell_services/monitor_services.ml
index 7b425001c..a581760d3 100644
--- a/src/lib_shell_services/monitor_services.ml
+++ b/src/lib_shell_services/monitor_services.ml
@@ -15,7 +15,12 @@ module S = struct
 
   let bootstrapped =
     RPC_service.get_service
-      ~description:""
+      ~description:
+        "Wait for the node to have synchronized its chain with a few \
+         peers (configured by the node's administrator), streaming \
+         head updates that happen during the bootstrapping process, \
+         and closing the stream at the end. If the node was already \
+         bootstrapped, returns the current head immediately."
       ~query: RPC_query.empty
       ~output: (obj2
                   (req "block" Block_hash.encoding)
@@ -39,7 +44,9 @@ module S = struct
 
   let valid_blocks =
     RPC_service.get_service
-      ~description:""
+      ~description:"Monitor all blocks that are succesfully validated \
+                    by the node, disregarding whether they were \
+                    selected as the new head or not."
       ~query: valid_blocks_query
       ~output: (obj2
                   (req "chain_id" Chain_id.encoding)
@@ -57,14 +64,17 @@ module S = struct
 
   let heads =
     RPC_service.get_service
-      ~description:""
+      ~description:"Monitor all blocks that are succesfully validated \
+                    by the node and selected as the new head of the \
+                    given chain."
       ~query: heads_query
       ~output: Block_hash.encoding
       RPC_path.(path / "heads" /: Chain_services.chain_arg)
 
   let protocols =
     RPC_service.get_service
-      ~description:"...FIXME..."
+      ~description:"Monitor all economic protocols that are retrieved \
+                    and succesfully loaded and compiled by the node."
       ~query: RPC_query.empty
       ~output: Protocol_hash.encoding
       RPC_path.(path / "protocols")