Alpha: fix typos and fill placeholders in services doc

docs/doc_gen/rpc_doc.ml

@@ -164,8 +164,8 @@ module Description = struct
     let pp_description ppf (service : _ RPC_description.service) =
       let open RPC_description in
       (* TODO collect and display arg description (in path and in query) *)
-      Format.fprintf ppf "%s%a"
+      Format.fprintf ppf "@[<h>%a@]%a"
-        (Option.unopt ~default:"" service.description)
+        Format.pp_print_text (Option.unopt ~default:"" service.description)
         Query.pp service.query
 
     let pp ppf prefix service =

src/proto_alpha/lib_protocol/src/apply_operation_result.ml

@@ -12,8 +12,10 @@ open Data_encoding
 
 let error_encoding =
   def "error"
-    (* FIXME RPC /chains/blocks/head/errors lint*)
+    ~description:
-    ~description:"... FIXME ..." @@
+      "The full list of RPC errors would be too long to include.\n\
+       It is available at RPC `/errors` (GET).\n\
+       Errors specific to protocol Alpha have an id that starts with `proto.alpha`." @@
   splitted
     ~json:(conv
              (fun err ->
@@ -655,7 +657,7 @@ let contents_result_list_encoding =
     | Contents_result_list (Cons_result (o, os)) ->
         Contents_result o :: to_list (Contents_result_list os) in
   let rec of_list = function
-    | [] -> assert false
+    | [] -> Pervasives.failwith "cannot decode empty operation result"
     | [Contents_result o] -> Contents_result_list (Single_result o)
     | (Contents_result o) :: os ->
         let Contents_result_list os = of_list os in
@@ -664,7 +666,7 @@ let contents_result_list_encoding =
             Contents_result_list (Cons_result (o, os))
         | Manager_operation_result _, Cons_result _ ->
             Contents_result_list (Cons_result (o, os))
-        | _ -> Pervasives.failwith "...FIXME..." in
+        | _ -> Pervasives.failwith "cannot decode ill-formed operation result" in
   def "operation.alpha.contents_list_result" @@
   conv to_list of_list (list contents_result_encoding)
 
@@ -683,7 +685,7 @@ let contents_and_result_list_encoding =
         Contents_and_result (op, res) ::
         to_list (Contents_and_result_list rest) in
   let rec of_list = function
-    | [] -> assert false (* FIXME error message *)
+    | [] -> Pervasives.failwith "cannot decode empty combined operation result"
     | [Contents_and_result (op, res)] ->
         Contents_and_result_list (Single_and_result (op, res))
     | (Contents_and_result (op, res)) :: rest ->
@@ -693,7 +695,7 @@ let contents_and_result_list_encoding =
             Contents_and_result_list (Cons_and_result (op, res, rest))
         | Manager_operation _, Cons_and_result (_, _, _) ->
             Contents_and_result_list (Cons_and_result (op, res, rest))
-        | _ -> Pervasives.failwith "...FIXME..." in
+        | _ -> Pervasives.failwith "cannot decode ill-formed combined operation result" in
   conv to_list of_list (list contents_and_result_encoding)
 
 type 'kind operation_metadata = {
@@ -845,7 +847,7 @@ let operation_data_and_metadata_encoding =
   conv
     (fun (Operation_data op, Operation_metadata res) ->
        match kind_equal_list op.contents res.contents with
-       | None -> assert false (* FIXME *)
+       | None -> Pervasives.failwith "cannot decode inconsistent combined operation result"
        | Some Eq ->
            (Contents_and_result_list
               (pack_contents_list op.contents res.contents),

src/proto_alpha/lib_protocol/src/delegate_services.ml

@@ -65,7 +65,7 @@ module S = struct
   let list_delegate =
     RPC_service.get_service
       ~description:
-        "List all registred delegates."
+        "Lists all registered delegates."
       ~query: list_query
       ~output: (list Signature.Public_key_hash.encoding)
       path
@@ -110,8 +110,8 @@ module S = struct
   let staking_balance =
     RPC_service.get_service
       ~description:
-        "Returns the total amount of token delegated to a given delegate. \
+        "Returns the total amount of tokens delegated to a given delegate. \
-         This includes the balance of all the contracts that delegates \
+         This includes the balances of all the contracts that delegate \
          to it, but also the balance of the delegate itself and its frozen \
          fees and deposits. The rewards do not count in the delegated balance \
          until they are unfrozen."
@@ -122,7 +122,7 @@ module S = struct
   let delegated_contracts =
     RPC_service.get_service
       ~description:
-        "Returns the list of contract that delegates to a given delegate."
+        "Returns the list of contracts that delegate to a given delegate."
       ~query: RPC_query.empty
       ~output: (list Contract_hash.encoding)
       RPC_path.(path / "delegated_contracts")
@@ -130,9 +130,9 @@ module S = struct
   let delegated_balance =
     RPC_service.get_service
       ~description:
-        "The includes the balance of all the contracts that delegates \
+        "Returns the balances of all the contracts that delegate to a \
-         to it. This excludes the delegate own balance and its frozen \
+         given delegate. This excludes the delegate's own balance and \
-         balances."
+         its frozen balances."
       ~query: RPC_query.empty
       ~output: Tez.encoding
       RPC_path.(path / "delegated_balance")
@@ -140,7 +140,7 @@ module S = struct
   let deactivated =
     RPC_service.get_service
       ~description:
-        "Returns whether the delegate is currently tagged as deactivated or not."
+        "Tells whether the delegate is currently tagged as deactivated or not."
       ~query: RPC_query.empty
       ~output: bool
       RPC_path.(path / "deactivated")
@@ -149,11 +149,10 @@ module S = struct
     RPC_service.get_service
       ~description:
         "Returns the cycle by the end of which the delegate might be \
-         deactivated, whether should she failed to execute any delegate \
+         deactivated if she fails to execute any delegate action. \
-         action until then. \
          A deactivated delegate might be reactivated \
-         (without loosing any rolls) by simply re-register as a delegate. \
+         (without loosing any rolls) by simply re-registering as a delegate. \
-         For deactivated delegate this value contains the cycle by which \
+         For deactivated delegates, this value contains the cycle by which \
          they were deactivated."
       ~query: RPC_query.empty
       ~output: Cycle.encoding
@@ -255,8 +254,6 @@ let requested_levels ~default ctxt cycles levels =
   | levels, cycles ->
       (* explicitly fail when requested levels or cycle are in the past...
          or too far in the future... *)
-      (* check_levels levels >>=? fun () -> *)
-      (* check_cycles levels >>=? fun () -> *)
       let levels =
         List.sort_uniq
           Level.compare
@@ -293,7 +290,7 @@ module Baking_rights = struct
          (req "level" Raw_level.encoding)
          (req "delegate" Signature.Public_key_hash.encoding)
          (req "priority" uint16)
-         (opt "timestamp" Timestamp.encoding))
+         (opt "estimated_time" Timestamp.encoding))
 
   module S = struct
 
@@ -323,7 +320,24 @@ module Baking_rights = struct
 
     let baking_rights =
       RPC_service.get_service
-        ~description: "...FIXME..."
+        ~description:
+          "Retrieves the list of delegates allowed to bake a block.\n\
+           By default, it gives the best baking priorities for bakers \
+           that have at least one opportunity below the 64th priority \
+           for the next block.\n\
+           Parameters `level` and `cycle` can be used to specify the \
+           (valid) level(s) in the past or future at which the baking \
+           rights have to be returned. Parameter `delegate` can be \
+           used to restrict the results to the given delegates. If \
+           parameter `all` is set, all the baking opportunities for \
+           each baker at each level are returned, instead of just the \
+           first one.\n\
+           Returns the list of baking slots. Also returns the minimal \
+           timestamps that correspond to these slots. The timestamps \
+           are omitted for levels in the past, and are only estimates \
+           for levels later that the next block, based on the \
+           hypothesis that all predecessor blocks were baked at the \
+           first priority."
         ~query: baking_rights_query
         ~output: (list encoding)
         custom_root
@@ -444,7 +458,21 @@ module Endorsing_rights = struct
 
     let endorsing_rights =
       RPC_service.get_service
-        ~description: "...FIXME..."
+        ~description:
+          "Retrieves the delegates allowed to endorse a block.\n\
+           By default, it gives the endorsement slots for bakers that \
+           have at least one in the next block.\n\
+           Parameters `level` and `cycle` can be used to specify the \
+           (valid) level(s) in the past or future at which the \
+           endorsement rights have to be returned. Parameter \
+           `delegate` can be used to restrict the results to the given \
+           delegates.\n\
+           Returns the list of endorsement slots. Also returns the \
+           minimal timestamps that correspond to these slots. The \
+           timestamps are omitted for levels in the past, and are only \
+           estimates for levels later that the next block, based on \
+           the hypothesis that all predecessor blocks were baked at \
+           the first priority."
         ~query: endorsing_rights_query
         ~output: (list encoding)
         custom_root

src/proto_alpha/lib_protocol/src/delegate_services.mli

@@ -83,19 +83,24 @@ module Baking_rights : sig
     timestamp: Timestamp.t option ;
   }
 
-  (** Compute the baking rights. By default, it computes the baking
+  (** Retrieves the list of delegates allowed to bake a block.
-      rights for the next block and only returns the first available
-      priority for bakers that appears in the 64 first priorities.
 
-      The optional arguments [levels] and [cycles] allows to compute
+      By default, it gives the best baking priorities for bakers
-      baking for an explicit list of levels or for all the levels of the given
+      that have at least one opportunity below the 64th priority for
-      cycles.
+      the next block.
 
-      The optional argument [delegates] allows to filter
+      Parameters [levels] and [cycles] can be used to specify the
-      the non-explicitly listed delegates out of the resulting list.
+      (valid) level(s) in the past or future at which the baking rights
+      have to be returned. Parameter [delegates] can be used to
+      restrict the results to the given delegates. If parameter [all]
+      is [true], all the baking opportunities for each baker at each level
+      are returned, instead of just the first one.
 
-      When [all=false], the function only returns the minimal priority
+      Returns the list of baking slots. Also returns the minimal
-      for each delegates. When [all=true], all priorities are returned. *)
+      timestamps that correspond to these slots. The timestamps are
+      omitted for levels in the past, and are only estimates for levels
+      later that the next block, based on the hypothesis that all
+      predecessor blocks were baked at the first priority. *)
   val get:
     'a #RPC_context.simple ->
     ?levels: Raw_level.t list ->
@@ -116,15 +121,22 @@ module Endorsing_rights : sig
     estimated_time: Timestamp.t option ;
   }
 
-  (** Compute the endorsing rights. By default, it computes the
+  (** Retrieves the delegates allowed to endorse a block.
-      endorsing rights for the next block.
 
-      The optional arguments [levels] and [cycles] allows to compute
+      By default, it gives the endorsement slots for bakers that have
-      baking for an explicit list of levels or for all the levels of
+      at least one in the next block.
-      the given cycles.
 
-      The optional argument [delegates] allows to filter the
+      Parameters [levels] and [cycles] can be used to specify the
-      non-explicitly listed delegates out of the resulting list.. *)
+      (valid) level(s) in the past or future at which the endorsement
+      rights have to be returned. Parameter [delegates] can be used to
+      restrict the results to the given delegates.  Returns the list of
+      endorsement slots. Also returns the minimal timestamps that
+      correspond to these slots.
+
+      Timestamps are omitted for levels in the past, and are only
+      estimates for levels later that the next block, based on the
+      hypothesis that all predecessor blocks were baked at the first
+      priority. *)
   val get:
     'a #RPC_context.simple ->
     ?levels: Raw_level.t list ->

src/proto_alpha/lib_protocol/src/helpers_services.ml

@@ -433,7 +433,10 @@ module S = struct
 
   let current_level =
     RPC_service.get_service
-      ~description: "..."
+      ~description:
+        "Returns the level of the interrogated block, or the one of a \
+         block located `offset` blocks after in the chain (or before \
+         when negative). For instance, the next block if `offset` is 1."
       ~query: level_query
       ~output: Level.encoding
       RPC_path.(path / "current_level")

src/proto_alpha/lib_protocol/src/level_repr.ml

@@ -53,13 +53,45 @@ let encoding =
         voting_period ; voting_period_position ;
         expected_commitment })
     (obj7
-       (req "level" Raw_level_repr.encoding)
+       (req "level"
-       (req "level_position" int32)
+          ~description:
-       (req "cycle" Cycle_repr.encoding)
+            "The level of the block relative to genesis. This is also \
-       (req "cycle_position" int32)
+             the Shell's notion of level"
-       (req "voting_period" Voting_period_repr.encoding)
+          Raw_level_repr.encoding)
-       (req "voting_period_position" int32)
+       (req "level_position"
-       (req "expected_commitment" bool))
+          ~description:
+            "The level of the block relative to the block that starts \
+             protocol alpha. This is specific to the protocol \
+             alpha. Other protocols might or might not include a \
+             similar notion."
+          int32)
+       (req "cycle"
+          ~description:
+            "The current cycle's number. Note that cycles are a \
+             protocol-specific notion. As a result, the cycle number starts at 0 \
+             with the first block of protocol alpha."
+          Cycle_repr.encoding)
+       (req "cycle_position"
+          ~description:
+            "The current level of the block relative to the first \
+             block of the current cycle."
+          int32)
+       (req "voting_period"
+          ~description:
+            "The current voting period's index. Note that cycles are a \
+             protocol-specific notion. As a result, the voting period \
+             index starts at 0 with the first block of protocol alpha."
+          Voting_period_repr.encoding)
+       (req "voting_period_position"
+          ~description:
+            "The current level of the block relative to the first \
+             block of the current voting period."
+          int32)
+       (req "expected_commitment"
+          ~description:
+            "Tells wether the baker of this block has to commit a seed \
+             nonce hash."
+          bool))
 
 let root first_level =
   { level = first_level ;